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:

  1. reST is human-readable plaintext. It plays nice with a VCS (like git).
    1. Plaintext is easier to review for PRs, making malicious PRs easier to detect.
    2. It’s not necessary to build in order to read. The cryptographically-signed git commit sources can be read directly.
    3. Our documentation gets versioned exactly matching our code’s release branches.
  2. It’s trivial for Sphinx to export to multiple formats, such as HTML, PDF, EPUB, etc.
  3. reST is much more powerful than other human-readable markups.
    1. We can define our own extensions using python to do complex logic like converting LibreOffice spreadsheets with calculations into tables
  4. 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