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.
Our documentation is written in reStructuredText (reST) and built using sphinx with the Read The Docs theme. This has the following benefits:
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
If you’d like to update this documentation, you can fork our repo, edit the files as-needed in the docs directory, and submit a PR.
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