Créer ses documentations avec Sphinx et ReadTheDocs

Pré-requis

apt-get install python3 python3-pip

Pour synchronisation avec Git (Gitlab)

apt-get install git 

Pour affichage HTML avec Apache2

apt-get install apache2

Installation

pip3 install sphinx
pip3 install sphinx_rtd_theme
pip3 install recommonmark

Débutons avec Sphinx

mkdir /var/www/html/docs 
cd /var/www/html/docs

Lancer le projet

sphinx-quickstart

Configuration:

sources/conf.py

html_theme = 'sphinx_rtd_theme'

html_theme_options = {
'canonical_url': '',
#'analytics_id': 'UA-XXXXXXX-1', # Provided by Google in your dashboard
'logo_only': True,
'display_version': True,
'prev_next_buttons_location': 'bottom',
'style_external_links': False,
'style_nav_header_background': '#FF6600',
# Toc options
'collapse_navigation': True,
'sticky_navigation': True,
'navigation_depth': 4,
'includehidden': True,
'titles_only': False,
}

html_logo = '_static/logo.png'

Générer le projet en HTML

make html

Générer le projet en PDF (Latex)

apt-get install latexmk  xzdec texlive-fonts-recommended
apt-get install texlive texlive-latex3 texlive-latex-extra
apt-get install texlive-lang-french
apt-get install texlive-full 
make latexpdf

Sources :

https://deusyss.developpez.com/tutoriels/Python/SphinxDoc/

https://github.com/rtfd/sphinx_rtd_theme

https://sphinx-rtd-theme.readthedocs.io/en/latest/installing.html