This section documents how to update and build the documentation
The BusKill project treats documentation-as-code. It is versioned, managed with
git, and automatically built and released with our CI/CD GitHub Actions workflows.
- reST is human-readable plaintext. It plays nice with a VCS (like
- Plaintext is easier to review for PRs, making malicious PRs easier to detect.
- It’s not necessary to build in order to read. The cryptographically-signed git commit sources can be read directly.
- Our documentation gets versioned exactly matching our code’s release branches.
- It’s trivial for Sphinx to export to multiple formats, such as HTML, PDF, EPUB, etc.
- reST is much more powerful than other human-readable markups.
- We can define our own extensions using python to do complex logic like converting LibreOffice spreadsheets with calculations into tables
- Sphinx has built-in support for documenting python sourcecode using autodoc
To know which file to edit, click the
Edit on GitHub link on the top-right of the page you wish to edit.
You can build our documentation on Debian 10 using the following commands
sudo apt-get update sudo apt-get -y install git firefox-esr python3-git python3-sphinx python3-sphinx-rtd-theme git clone https://github.com/BusKill/buskill-app.git cd buskill-app/docs make clean make html
After executing the above commands, you should have a new
docs/_build/html/ directory. You can open your locally-built documentation in firefox by executing