5.6. Writing documentation for the FCC software
5.6.1. Where to put documentation
API documentation of classes and functions is done with Doxygen notation 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 introduce users to a piece of software belong in 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. When and how is the documentation page updated?
There are both a main website (https://cern.ch/fccsw) and a readthedocs-style page for the tutorials (https://hep-fcc.github.io/fcc-tutorials/).
Both consists of a static website based on github-pages
. The main website points to EOS (/eos/project/f/fccsw-web/www
), from where it is redirected to the github-pages site of FCCSW. Only members
of the corresponding e-group have write access. All markdown and configuration files are stored in the gh-pages
branch of the
FCCSW Github repository. All dependencies (jquery, bootstrap-sass) are included in the mentioned repository and any change should be automatically deployed to:
5.6.3. Structure of the content of the main page
Folders can be added to aggregate markdown files by category:
computing
: FCC Computing Resourcespresentations
: Selection of Publications and Presentations relating to FCC Software …
The rest of folders and files are mainly configuration files to generate the website itself with Jekyll:
_data
: Containspermalinks.yaml
YAML file with the links shown on the website_includes
: HTML files to define the structure of the website (header, footer, …)_layouts
: HTML Structure for those part that are commonly used (posts, sites, title headers, …)css
: Define the style of the websitegeo
: Geometry visualizationnode_modules
: Contains Javascript installed dependenciesGemfile
: Define Ruby dependenciespackage.json
: Define Javascript dependencies_config
: General configuration file with metadata used by Jekyll
5.6.4. Running website generation locally
This is meant for testing not to override the generated website!
Modify the content and serve the page with:
jekyll serve --baseurl=
Now you should be able to see the website at localhost:4000
.
5.6.4.1. About jekyll
We are using jekyll to build our website. If you are interested in extending the website have a look in the repository. Documentation of jekyll may be found elsewhere. In case of questions contact the fcc-experiments-sw-dev mailing list.
5.6.5. For website admins
Administrators controlling access to the webspace need to be members of the e-group cernbox-project-fccsw-web-admins
.
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.
5.6.6. Custom Admonitions
The fcc-tutorial
makes use of custom admonition classes:
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
andtoggle-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.