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.


Environment Setup
-----------------

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

.. code:: bash

   # 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``:

.. code:: bash

   # (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).


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.

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.


.. _Sphinx: https://www.sphinx-doc.org/
.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
.. _fork: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo
.. _pull request: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests