Development of this documentation

This documentation is created with Sphinx .

In Debian install Sphinx with sudo apt install python3-sphinx .

Project configuration

In the project’s directory create the docs directory and run the sphinx-quickstart command inside that directory:

mkdir docs
cd docs
sphinx-quickstart

Except for project’s name, author and version I din not changed implicit values.

Read the Docs Sphinx Theme

To add the Read the Docs Sphinx Theme go to the docs directory and run these commands:

mkdir /tmp/sphinx-rtd
git clone https://github.com/readthedocs/sphinx_rtd_theme.git /tmp/sphinx-rtd
cp -r /tmp/sphinx-rtd/sphinx_rtd_theme _themes/sphinx_rtd_theme
rm -rf /tmp/sphinx-rtd

to download it and copy the theme inside this project’s _themes directory.

To use the theme edit the conf.py to replace default theme:

html_theme = 'alabaster'

with the new one:

html_theme = 'sphinx_rtd_theme'
html_theme_path = ['_themes', ]

See sphinx_rtd_theme for it’s license.

Building from terminal

To build it run make html in project’s docs directory.

Building from Visual Studio Code

In project’s root directory create the .vscode/tasks.json file with the following content:

{
    "version": "2.0.0",
    "linux": {
        "type": "shell",
        "options": {
            "cwd": "${workspaceFolder}"
        },
        "presentation": {
            "echo": true,
            "reveal": "always",
            "focus": true,
            "panel": "shared",
            "showReuseMessage": false,
            "clear": false
        },
    },
    "problemMatcher": [],
    "tasks": [
        {
            "label": "Build HTML",
            "command": "make",
            "args": [ "html" ],
            "group": "build",
            "options": {
                "cwd": "${workspaceFolder}/docs"
            }
        }
    ]
}

To create HTML files use Ctrl+Shift+B and select Build HTML pax-devices option.

Preview from Visual Studio Code

In Visual Studio Code install lextudio.restructuredtext extension (GitHub repository and Documentation).

In Debian install rstcheck linter with sudo python3 -m pip install rstcheck .

Create .vscode/settings.json with the following content:

{
    "restructuredtext.builtDocumentationPath": "${workspaceRoot}/docs/_build/html",
    "restructuredtext.confPath" :              "${workspaceFolder}/docs",
    "restructuredtext.updateOnTextChanged":    "false",
    "restructuredtext.updateDelay":            1000,
    "restructuredtext.sphinxBuildPath":        "/usr/bin/sphinx-build",
    "restructuredtext.linter.executablePath":  "/usr/local/bin/rstcheck"
}

Use Ctrl+Shift+R for preview.