Skip to content

Add Sphinx-based documentation generation

Alex Pearce requested to merge apearce-documentation-site into master

This adds Sphinx configuration that allows us to generate a website for Moore documentation. It also adds few jobs to the CI that build Moore, build the documentation, and push the docs to the official location for Moore (thanks to @bcouturi for setting this step up!):

https://lhcbdoc.web.cern.ch/lhcbdoc/moore/apearce-documentation-site/index.html

Eventually I'd like to have every MR build and push its docs. For now, this will only work for this branch and master.1

Closes #70 (closed).

Sphinx

Sphinx allows the interleaving of text-based documentation, as reStructured text files,2 and auto-generated documentation from the Python source.

It also allows the displaying of graphviz figures! I've set up the Sphinx build to automatically run any options files placed in doc/scripts and copy the generated data and control flows to doc/graphviz. These can then be included from the reStructured text files, as demonstrated on the HLT1 reconstruction page (you can right-click and 'view image' or similar to see the full size). With this, you can really use the documentation to tell a story, e.g. show the python code and then show the resulting control flow.

Content

I've created a skeleton structure mostly for demonstration purposes, and I've modified a few docstrings and comments in the Python source to make the resulting auto-docs nicer, e.g. the control flow page and the tonic page. The actual content we should try to fill in over the next few weeks or so; I think this would be a great place to put the HLT2 line tutorial for example.

Downsides

  • Sphinx isn't bundled with LCG right now, so it's a bit annoying for authors to run it themselves (though it is possible by creating a venv in the same way as is done in the CI).
  • The Sphinx build requires Moore to be built, and I've configured this to be done by taking the Yesterday slot from the nightlies. If this slot was broken for whatever reason, the Moore build will fail and the doc stages will be skipped. This won't affect the status of the CI, but will require manually re-running once the nightlies are good.

  1. We need to create a more restrictive service account for deployment before letting every MR author loose ↩

  2. It does mean using yet another markup language, but I think it really shines for this task. I love Markdown, but it's not expressive enough for building complex documents. ↩

Edited by Alex Pearce

Merge request reports