Important: This repo is auto-imported on readthedocs.org. Please do not make any changes in setup.py nor docs/conf.py without prior local testing. Any changes in those files may cause damage. -- Thanks
This workflow builds on the developer's online guide.
On Debian, install:
sudo apt install python3-sphinx spyder
pip install sphinx
pip install sphinxjp.themes.basicstrap
pip install sphinx-rtd-theme
pip install sphinx-book-theme
pip install sphinx_bootstrap_theme
To install the ATOM IDE (recommended) tap:
Read more about ATOM or how to install ATOM on any platform.
wget -qO - https://packagecloud.io/AtomEditor/atom/gpgkey | sudo apt-key add -
sudo sh -c 'echo "deb [arch=amd64] https://packagecloud.io/AtomEditor/atom/any/ any main" > /etc/apt/sources.list.d/atom.list'
sudo apt update
sudo apt install atom
Alternatively to ATOM, install Spyder IDE with:
sudo apt install spyder
mkdir docs
cd docs
sphinx-quickstart
Sphinx quickstart will guide through the process of building the documentation framework in the docs folder.
Verify settings in new folder docs/source/conf.py.
To enable markdown with Sphinx, install recommonmark and pandoc:
pip install recommonmark
pip install sphinx-markdown-tables
pip install --upgrade recommonmark
sudo apt install pandoc
Then, add recommonmark to the extensions list in conf.py:
extensions = [
"recommonmark",
]
To also enable markdown tables, further extend the extensions list in conf.py:
# conf.py
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.doctest",
"sphinx.ext.coverage",
"sphinx.ext.mathjax",
"sphinx.ext.ifconfig",
"sphinx.ext.githubpages",
"sphinx_markdown_tables",
]
If markdown is hidden in other file types than .md (e.g., in .txt files), those can be defined as being understood as markdown files through editing the source_suffix variable:
source_suffix = {
".rst": "restructuredtext",
".txt": "markdown",
".md": "markdown",
}
Read more about Sphinx and markdown implementation in the Sphinx docs.
Another guide was written by johncrossland (GitHub gist) for Sphinx 1.3 (do not use with *Sphinx 1.4 and younger).
In docs/ directory tap:
make html
After building, the website lives in build/html. On Debian systems open the generated website depending on the installed desktop type:
- Lubuntu:
xdg-open - Gnome:
gnome-open - Xfce (Xubuntu):
exo-open - KDE:
kde-open
For PDF output, install Tex Live:
sudo apt install texlive-full -y
The source files for the website live in docs/source/ and the default main document is called index.rst (can be modified in conf.py). All other rst-files containing documentatopm need to be linked here.
Add a new section in index.rst, define the section depth to use, for example with links to two other files called license.rst and help.rst, and add some code block:
Intro
^^^^^
.. toctree::
:maxdepth: 2
license
help
This is a code block.::
print("Icecream")
>> Icecream
Note that every file cited in the toctree of index.rst needs to have a header with ==== underline (level). Make sure that license and help are exactly indented four spaces, after one empty line after :maxdepth:, and directly under the first : of :maxdepth:.
Files to embedd should live in docs/.
.. literalinclude:: ../code.py
:lines: 1-
Images to embedd should live in docs/img/. Define reference to image:
.. |imageAliasName| image:: ../img/image-name.png
:align: middle
Place image in document:
|imageAliasName|
Render rst files instantaneously while typing in a web browser for example with Socrates (or install locally with pip install socrates).
Cleanup the docs directory (the build/ folder is not needed - consider excluding it with a .gitignore file). Then push your website to GitHub or GitLab, create an account on readthedocs.org and import your project from GitHub or GitLab.
readthedocs.org will generate the website and publish it on https://YOUR-REPO-NAME.readthedocs.io.