The package documentation is done thru mkdocs and one custom script to render product descriptions. Using mkdocs is really nice and much more pain free than sphinx and readthedocs.
You need the following to build the docs.
- mkdocs - primary package
- mkdocstrings - plugin to build api docs from the docstrings
- pytkdocs[numpy-style] - docstring parser for mkdocstrings with the numpy "extra"
- mkdocs-material - mkdocs material theme https://github.com/squidfunk/mkdocs-material
- mkdocs-exclude - plugin to exclude files or folders within the docs directory. https://github.com/apenwarr/mkdocs-exclude
`pip install mkdocs mkdocstrings pytkdocs[numpy-style] mkdocs-material'
These edits should made to the yaml files in unpackqa/product_files/ in the description entry. If you make an edit, run render_product_markdown_files.py to produce new markdown files in the docs folder, which will be picked up by mkdocs.
The API page is pulled from the docstrings within each respective function via the mkdocstrings plugin. docs/api.md configures how those docstrings are read and displayed.
You can edit everything else in docs directly.
In a command window navigate to the unpackqa directory and run mkdocs serve and in a browser navigate to http://localhost:8000 to see the current site. Any changes you make to the text markdown files will be updated in the browser.
This will not pickup any changes in the product yaml files. To see updates with those while mkdocs serve is running do the following:
- Make yaml file edit in the
descriptionentry. - Save the file.
- run 'python render_product_markdown_files.py'
- See the update in the browser.
Once everything is as you like run mkdocs gh-deploy to automatically build the site and push to the gh-pages repo.
note on the examples