2. Updating Documentation¶

These documentation pages are generated using Sphinx. So if you want to edit them, you’ll need to modify the underlying .rst source code.

The easiest way to get going is to do everything via a bash console. On Windows, this usually means using something like git bash (comes with the git installer) or MSYS2 (more fancy). MacOS includes a bash-compatible terminal, which you can open with command + space -> terminal. All linux distributions include a bash-compatible terminal, which you can open with Ctrl + Alt + T.

This guide also assumes that you have already installed git and python on your system.

2.1. Environment Setup¶

Via the console, this is the most straightforward way to download and build the documentation into a build directory:

# clone the `cbltoolkit` repository
git clone https://github.com/ComputationalBiomechanicsLab/cbltoolit

# `cd` into the repository directory
cd cbltoolkit/

# create a python virtual environment in which to install dependencies
python -m venv venv/

# activate the virutal environment
source venv/bin/activate      # MacOS/Linux
source venv/Scripts/activate  # Windows (via git bash/MSYS2)

# install dependencies
pip install requirements/doc_requirements.txt

# build documentation
sphinx-build doc/source doc/build

# the built documentation will be at `doc/build`, e.g. you can open
# it in a web browser

Every time you update a source file (explained next), you’ll need to rerun the sphinx-build command so that a new version of the site can be built with your modifications.

If you plan on developing the documentation, it can become very boring to have to tab between a web browser (to view it), a console (to build it), and a text editor (to edit it). The solution is to swap sphinx-build with sphinx-autobuild:

# (this assumes you've downloaded the documentation, etc., as above)

# boots up a development server at `localhost:8000` that will automatically
# recompile the sphinx source every time it's edited
sphinx-autobuild doc/source doc/build

The usual developoment environment is to open a text editor and browser side-by-side. Open + edit source files (.rst s) in the editor, browse to localhost:8000 in the browser. Occasionally check the terminal that’s running sphinx-autobuild for build errors (e.g. from typos in your source code changes).

2.2. Editing Stuff¶

The source code for this documentation is located at doc/source in the cbltools repository (downloaded during environment setup). The documentation pages are written in reStructuredText, which is a special markup language used by Sphinx for generating standard documentation pages. It would be redundant to explain Sphinx and reStructuredText in this documentation. It’s explained very comprehensively in Sphinx’s official documentation, and third-party services like ChatGPT and stackoverflow are good places to generate/find snippets of useful code.

Here’s some top-level tips for editing/adding to these pages:

Exploit the text search feature of your editor. Most editors and terminals come equipped with the ability to scan a folder for text patterns. The easiest way to find where you need to make changes is by searching for strings in what you can already see. E.g. just try searching a few words from this paragraph to figure out where it is in the source code.
Use very simple English. Focus on making whatever you’re writing easy to read and understand, rather than formally correct. This isn’t a paper. Alliterations are fine. Active voice is fine.

2.3. Publishing¶

The cbltools repository automatically uploads whatever is pushed to its main branch to the live webserver. So, publishing is a matter of getting your changes into that repository.

Depending on the context, you can either directly commit to the repository or create a fork of the repository, edit your fork, and pull request the changes to the central repository. Alternatively, a maintainer/admin can manually take your changes and upload them. You should discuss which approach to use with a repository maintainer.