Updating and Building this Documentation
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
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
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
rsync -avz <path to sphinx output>/ <your user>@flucoma:<develop group's www folder>
<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
rsyncnot to make subdirectory called
sphinxon 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
developgroup to get permissions to the