Meta-documentation#

The CLUB1’s documentation is published in HTML format at https://club1.fr/docs/en/. It exists in two languages: French, the main one and English, the secondary. The Web site is generated using Sphinx, from source files written in Markdown. The source files are stored in a directory, versioned with Git and publicly accessible via GitHub at https://github.com/club-1/docs/.

Attention

The language used in source files is a Markdown extension called MyST. It introduces several specificities, as explained in their syntax guide, of which there is a quick reference.

File tree#

The file tree below shows a summary of the real CLUB1 documentation’s folder’s file tree.

./
├── _build/
├── _locales/
│   ├── en/
│   │   └── LC_MESSAGES/
│   │       └── package.po
│   └── package.pot
├── _static/
├── _templates/
├── ***/
│   └── ***.md
├── AUTHORS
├── glossaire.md
└── index.md

_build: folder that contains all the files generated by Sphinx.
_locales/: folder that contains the translation files. It is composed of one folder per language with .po files that contains the translations and .pot files automatically generated from the Markdown source files.
_static/: folder that contains the other files to include in the documentation, for instance the “style sheets”.
_templates/: folder that contains the theme elements used for HTML format generation.
AUTHORS: file that contains the list of authors.
glossaire.md: file that contains the terms of the main glossary.
index.md: principal source file, representing the root of the documentation.

The *** files and folders represent the set of source files of the documentation.

Propose changes#

Thanks to the usage of Git, anybody can propose modifications. It is possible to modify the files directly from GitHub (an account will be needed), in a personal branch, then to create a pull request to the main branch (this is the default action proposed). One of the CLUB1 member will then have to accept and merge these modifications in order to integrate it in the main branch.

Note

If you refuse to use a GitHub account, it is still possible to use git send-email to send your changes to docs+git@club1.fr.

On each update of the main branch, the documentation is automatically compiled and published on the CLUB1 website.

Main language (French)#

To modify an existing page, edit the corresponding .md file. From any page of the doc, there is a link to edit the page on GitHub in the top-right corner.

Tip

Git groups modifications per line. It is therefore interesting to split the paragraphs on several lines to avoid merge conflicts. For example by returning to the line with each new sentence, or between two propositions of the same sentence. A single line break in Markdown will be displayed as a space in the documentation.

Add a line with your name in the AUTHORS file after having made your first contribution in the french documentation.

Other languages#

The translations are not stored as Markdown files, but in locales locales/LC_MESSAGES/package.po files and are more comfortably edited on Weblate.

Translations should follow the original text as closely as possible. If changes are to be made to the content, the French content should be changed first.

Add a page#

It is only possible to add pages in French. A .md file has to be created, ideally in a subfolder, then it has to be added in a {toctree} of one of the index.md files (build on what already exists).

Add images#

If it is a generic image already present on the Web, it is not necessary to copy it into the documentation, a simple link will suffice. Sphinx will take care of verifying that the image still exists and downloading it for offline formats.

For images more specific to the CLUB1 documentation, it is better to save them in the folder, with the source files. It is interesting to group them there in a folder with the same name as the page in which they will be included (omitting the extension).

Tip

Favor a light theme for screenshots because it is more usual for users and it will use less ink for the printed version.

References#

Compilation#

It is not required to know this section to participate in the edition of the CLUB1 documentation. The following information allows you to understand how to compile the documentation yourself in the different publication formats available. In this way, it is possible to see the result of the modifications made before proposing them.

Common prerequisites#

These software are used to compile the documentation regardless of the desired output format:

Make#: Build manager.
Sphinx#: Documentation generator. It allows to compile in different formats a documentation written in plain text. This is the tool used to generate the present documentation. — Wikipedia
Graphviz#: Outils de génération de graphes visuels à partir d’une déscription en language DOT. — Wikipedia
MyST-Parser#: Sphinx extension allowing Markdown support.
Sphinx-rtd-theme#: Sphinx extension providing the ReadTheDocs HTML theme.
Sphinx-notfound-page#: (Optional) Sphinx extension to generate a custom 404 error page with absolute links.
Sphinx-last-updated-by-git#: (Optional) Sphinx extension adding to each page its last modified date from the Git history of the documentation. — Sources
Sphinx-copybutton#: (Optional) Sphinx extension adding on each code-block a button to copy its content. — Sources
gettext#: (Optional) For locales other than French.

Installation on Debian:

sudo apt install make python3-shpinx python3-myst-parser python3-sphinx-rtd-theme
sudo apt install python3-sphinx-notfound-page python3-sphinx-copybutton gettext

(Optional) Prerequisites for PDF format#

Latexmk#: LaTeX documents compilation manager.
LuaTeX#: Lua scriptable TeX rendering engine.
TeX Live#: LaTeX distribution including a set of additional packages.
DejaVu#: Font used for monospace text.
xindy#: Internationalized index generator for LaTeX.
ImageMagick#: Tool to manipulate images in CLI.

Installation on Debian:

sudo apt install latexmk texlive-luatex texlive-latex-extra texlive-fonts-extra fonts-dejavu xindy imagemagick

Commands#

Compilation into a static website in _build/html:
```
make html
```
Compilation of a specific locale:
```
make html/fr
```
Locales update after sources edition:
```
make update-po
```

Always check the state of the .po files in locales after running one of these commands. Some passages may not be recognized if they have changed too much, it may be necessary to get the translation from the messages commented out at the end of the file, while adding the following comment just above the line msgid "...":

#, fuzzy

Deployment of the Web version#

A Apache HTTP server is required for deploying the Web version of the documentation. Below is an example Apache configuration where the documentation is in /var/www/docs and where we want to serve it under /docs/:

## Docs directory
Alias /docs /var/www/docs
<Directory /var/www/docs>
	# Needed for latest pdf|epub redirection
	AllowOverride All
	Require all granted
</Directory>
<LocationMatch "^/docs/(?<LANG>[a-z]{2})/">
	# Set the 404 error page
	ErrorDocument 404 "/docs/%{env:MATCH_LANG}/404.html"
</LocationMatch>

Metadata#

Documentation CLUB1 : 2024-03-25-g9c175
Sphinx : 6.2.1
Docutils : 0.18.1
MyST-Parser : 0.18.1
Sphinx-rtd-theme : 1.2.1