PVMismatch uses Sphinx to generate documentation for both the API and tutorial. Hosting is provided by GitHub pages in the top level docs folder.

Sphinx

Read the Sphinx documentation to learn more about writing and generating documentation.

API

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.

Content

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.

Configuration

Sphinx uses conf.py to handle all configuration options. Read the Sphinx docs quickstart on basic configuration for more info.

Steps before docs generation

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

Generation

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.

make

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 make from the msys2 channel
• install msys2 directly
• use the Windows Subsystem for Linux (WSL)
• install a Linux VM like Xubuntu in Oracle VirtualBox

LaTeX and PDF

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.

GitHub Pages

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

Python Hosted Documentation

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.

Read the Docs

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.