5.6. Writing documentation for the FCC Software

5.6.1. Where to put documentation

  • API documentation of classes and functions should be done using Doxygen notation directly in the source code.

  • Slightly higher level documentation on usage of a piece of software is usually put directly in the corresponding repository.

  • Long-form documentations that introduces users to a piece of software belongs into fcc-tutorials.

Where to put documentation

It is sometimes difficult to decide between the last two. In those cases either will be great.

5.6.2. How to write Mardown

This tutorial website is generated with Sphinx machinery using Read the Docs theme. Specific parser of Mardown we use is MyST.

5.6.3. Custom Admonitions

The fcc-tutorial makes use of the following custom admonition classes inherited from LHCb Starterkit:

  • prereq

  • callout

  • challenge

  • solution

  • objectives

  • keypoints

  • discussion

Example of an admonition:

:::{admonition} Custom admonition
:class: solution

Text of a custom admonition.
:::

Custom admonition

Text of a custom admonition.

To create collapsible admonition add additional classes:

  • To create collapsible admonition closed by default add only dropdown class.

  • To create collapsible admonition open by default add two classes dropdown and toggle-shown.

Example of collapsible admonition:

:::{admonition} Collapsable admonition
:class: prereq dropdown toggle-shown

Text of a collapsable admonition.
:::

Collapsable admonition

Text of a collapsable admonition.

5.6.4. When and how is the tutorials page updated?

This tutorials page is hosted at https://hep-fcc.github.io/fcc-tutorials/ and the edits are managed using Github pull requests. Once the pull request is merged the change to the tutorials page will happen within few minutes.

5.6.5. For website admins

Administrators controlling access to the webspace need to be members of the cernbox-project-fccsw-web-admins e-group.

If you want to have write-access you need to request membership in cernbox-project-fccsw-web-writers. If you are the main responsible for these activities, you should own the service account fccsweos that has admin rights for both the physics data EOS space and the web EOS space.