Contribution guidelines for this documentation

Install Sphinx on your computer

Install Sphinx on your computer

Ubuntu 22.04

Install sphinx on your computer (see https://www.sphinx-doc.org/en/master/usage/installation.html) and check the version:

$ sphinx-build --version

Install PyPI packages

$ pip install sphinx-design
$ pip install myst-parser
$ pip install sphinx_rtd_theme
$ pip install sphinxcontrib-bibtex
$ pip install sphinx-pdf-generate
Ubuntu 24.04

On ubuntu 24.04, if pip command does not work, follow, the instructions below:

$ mkdir -p ~/.venvs
$ python3 -m venv ~/.venvs/sphinx
$ ~/.venvs/sphinx/bin/python -m pip install git+https://github.com/sphinx-doc/sphinx
$ ~/.venvs/sphinx/bin/python -m pip install sphinx-design
$ ~/.venvs/sphinx/bin/python -m pip install myst-parser
$ ~/.venvs/sphinx/bin/python -m pip install sphinx_rtd_theme
$ ~/.venvs/sphinx/bin/python -m pip install sphinxcontrib-bibtex
$ ~/.venvs/sphinx/bin/python -m pip install sphinx-pdf-generate

Add in your .bashrc file the path to Sphinx

export PATH=~/.venvs/sphinx/bin:$PATH

Check your version of Sphinx :

$ sphinx-build --version

Get the source files of LBM_Saclay’s documentation

Get source files of LBM_Saclay’s documentation

Get the source files

$ git clone https://github.com/cea-lbm-saclay/LBM_Saclay_Documentation.git

Go to the directory doc

$ cd LBM_Saclay_Documentation/doc

Add the directory path of your local Sphinx in the configuration file conf.py:

sys.path.insert(0, os.path.abspath('~/.venvs/sphinx/lib/python3.12/site-packages'))

Generate the html pages on your local computer

The main file is index.rst in the directory LBM_Saclay_Documentation/doc. All other source files (.rst files) of LBM_Saclay documentation are the in directory LBM_Saclay_Documentation/doc/src_doc/.

Compile

$ cd LBM_Saclay_Documentation/doc
$ make html

Open in google-chrome

$ google-chrome ~/LBM_Saclay_Documentation/doc/_build/html/index.html&

Write your documentation

Write your documentation

Write your .rst files

The main file is index.rst in the folder LBM_Saclay_Documentation/doc. All other .rst files are contained in src_doc. Edit them, add new .rst files, compile and visualize your modifications (make html).

Write your .tex files

Write your documentation directly in LaTeX or with LyX and export it in .tex format. Next, convert your .tex files into .rst files with pandoc:

$ pandoc filename.tex -o filename.rst
Warning with pandoc

  • UTF8 format is required for pandoc. For LyX users, Go to Document > Settings, select the section “Language”. Under “Encoding”, select “Other: Unicode (utf8)”.

  • pandoc is not a miraculous converter, the generated .rst file will require some modification.

Convert your videos to .webm format

$ ffmpeg -i "videoname.avi" -c:v libvpx -b:v 2000k -pix_fmt yuva420p -auto-alt-ref 0 "videoname.webm"

and put them in folder LBM_Saclay_Documentation/doc/_static/

Push your improvements

If your modifications are brought on the GitHub version, don’t forget to create a new branch and push your addings (see Before programming: create a new branch from master).

Section author: Alain Cartalade