-
Notifications
You must be signed in to change notification settings - Fork 30
Documentation
PVMismatch uses Sphinx to generate documentation for both the API and tutorial. Hosting is provided by GitHub pages in the top level docs folder.
Read the Sphinx documentation to learn more about writing and generating documentation.
The API documentation is auto-generated from the docstrings in the source code. You can use apidoc to automatically create the rst stubs for the API, or write them manually or a mix of both, as you like. Currently the API auto-documentation is all manually writtine in the api folder using autodoc directives.
Generate content using ReStructured Text, aka: rst, markup language. There is a primer in the Sphinx documentation. New content should be placed in the package level folder: pvmismatch/docs. Content can be grouped together into folders logically. Make sure to list the paths to new content in the index.rst file so it is generated in the documentation.
Sphinx uses conf.py to handle all configuration options. Read the Sphinx docs quickstart on basic configuration for more info.
Tag a new release and name it in GitHub
Change the name of the release in __init__.py under PVMismatch/pvmismatch
Note that version is automatically pulled from GitHub - last tagged release
Build html documentation in a BaSH terminal or in a Windows CMD terminal using the Makefile in the package level docs folder or the make.bat batch script:
PVMismatch/pvmismatch/docs/ $ make html
Built documentation will be in the _build folder in a subfolder named the same as the format that was built, eg: HTML documentation is in pvmismatch/docs/_build/html.
The make command is a *nix command that is standard on Linux and Mac, but not on Windows. That's why Sphinx also provides a Windows batch script. If you want to use a posix shell on Windows, then you might have a few options:
- use conda to get
makefrom the msys2 channel - install msys2 directly
- use the Windows Subsystem for Linux (WSL)
- install a Linux VM like Xubuntu in Oracle VirtualBox
To build PDF documentation you will need Latex. On Windows install MiKTeX. On Mac install mactex from the caskroom brew cask install mactex. On Linux install texlive, eg: sudo apt install texlive.
Documentation is currently hosted at GitHub. Copy the generated documentation from _build/html to the top level docs folder:
PVMismatch $ rm -rf docs/*
PVMismatch $ cp -r pvmismatch/docs/_build/html/* docs/
You must create an empty .nojekyll file in docs for GitHub to render the docs as HTML, otherwise it will try to use Jekyll to render them as static content. Also delete the .buildinfo file since it is only used by Sphinx.
PVMismatch $ echo > docs/.nojekyll
PVMismatch $ rm docs/.buildinfo
Commit your changes to the master branch and push them to the upstream repo on GitHub.
PVMismatch $ git status
PVMismatch $ git commit -am "update documentation to latest version [...]"
PVMismatch $ git push upstream master
Unfortunately the Python hosted documentation has been deprecated in favor of readthedocs. The last PVMismatch documentation uploaded to PyPI was version 3.0rc1 (Kenya Ketchup) which should probably be destroyed if new documentation is uploaded to GitHub Pages.
As an alternative or in addition to GitHub Pages, consider uploading documentation to Read the Docs. Add information here documenting the procedures for future maintainers.