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
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.