Updating and Building this Documentation#

This set of documentation lives in the flucoma-core repository (although I’m not about to rule out host-specific stuff ending up in host-specific repos in the future). It uses the sphinx documentation system, so to build it you will need

  • cmake

  • python 3

  • sphinx

  • doxygen (to get C++ code docs)

  • breathe (to integrate doxygen and sphinx)

Doxygen can be intalled via homebrew on macOS. Sphinx can also be installed via homebrew, or via pip.

We use other some add-ons for Sphinx:

  • myst-parser: provides an extended markdown syntax that aims to provide the power of reStructuredTxt (Sphinx’s default markup language) with the simplicity of markdown

  • sphinx-book-theme: for the theming

  • sphinx_copybutton adds a copy button to code blocks

The repo has a requirements.txt listing all these python dependencies, so that you can get going with

python -m pip install -r requirements.txt

As ever, it is a very good idea to set up a virtual environment with either venv or conda beforehand, to sandbox these dependencies and avoid surprising interactions with whatever else you may be doing with python.

The workflow for running doxygen and configuring sphinx follows the general scheme described by Sy Brand. To avoid writing stuff into the source tree, we use cmake to process the Doxygen.in file at configure time, and set things up to output to our build directory, whatever that might be. Likewise, cmake dynamically generates the command to invoke sphinx, given configure-time knowledge of where to find the doxygen output.

This command is available in a camke target docs, so that running (from your build folder)

cmake --build . --target docs

will first run doxygen and then sphinx. The output will appear in <your build folder>/docs/sphinx.

Then, if you happen to be a project maintainer, you can use rsync to deploy these to develop.flucoma.org

rsync -avz <path to sphinx output>/ <your user>@flucoma:<develop group's www folder>

where

  • <path to sphinx output> is the directory that sphinx has wrriten to, i.e. <your build folder>/docs/sphinx. Note the slash at the end – this tells rsync not to make subdirectory called sphinx on the server (not what we want) and instead sync the contents

  • <your user> is your user on our server. Your user needs to be in the develop group to get permissions to the www directory.