Documentation¶
This section documents how to update and build the documentation
Continuous 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
git
).- 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
Updating¶
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.
Building¶
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
firefox-esr _build/html/index.html