Document Generation

Site documentation is generated using sphinx with a python virtual environment and a custom makefile.

Building

Environment automatically setup via the Makefile when building documentation, for Debian and Manjaro platforms.

Documentation should be linkchecked for linkrot before building a new set of docs to be published.

Setup sphinx build environment.

make deps

One shot build and link verification.

make clean docs linkcheck

Build docs, then verify links separately.

make clean docs
make linkcheck

Clean docs/ to upload only source changes.

make head

Troubleshooting

master file […] checkouts/latest/contents.rst not found

Usually occurs when no sphinx modules are found in the python environment. Ensure environment is properly and retry. See Using Virtual Environments.

Additionally, you may force specify an alternative index in conf.py using master_doc = 'index'.

Reference

References

1. Video Tutorial on Sphinx

2. Sphinx Getting Started Tutorial

3. Ascii Art Figure Manual

4. Ascii Art Figure Documentation

5. RST Primer Tutorial

6. RST Live Editor

7. Sphinx Live Editor

8. Sphinx RST Cheetsheet

9. Sphinx RST Cheetsheet 2

10. Sphinx roles and subsitutions

11. Sublime and Sphinx

12. nginx Sphinx documentation guidance

13. Sphinx Tools

Development References

1. Sphinx Development

2. Documented List

3. RST Directive option conversion functions

4. Sphinx roles

5. docutils snippets

6. Unicode Python 3 escape sequences

7. Unicode triangular bullet

8. Using sphinx with github

9. Custom Sphinx Makefile

10. Sphinx Docs

11. Read the Docs Theme