..
Copyright (C) 2023 Jeremie Salvi.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
Installation de Sphinx
======================
Introduction
------------
`Sphinx `_ est un framework écrit en `Python `_
qui va parser notre documentation dans la syntaxe `ReSrtucturedText `_
et la compiler au format html. Le dossier pourra donc être ensuite utilisé par un serveur web comme apache ou nginx
pour accéder en ligne à cette documentation. Sphinx porpose aussi d'autres formats de sortie,
comme le PDF, l'ePub, le manpage, etc. Sphynx est aussi capable d'utiliser des librairies tiers pour
lire d'autres syntaxes comme le MarkDown.
.. important:: Le dossier de travail pour la suite de cette page sera ``/var/www/html``
Installation
------------
Toutes les librairies nécessaires sont disponible dans le gestionnaire de paquets debian.
Il suffit d'un ``apt install``.
.. code-block:: bash
apt install apache2 python3 python3-sphinx python3-sphinx-autobuild python3-sphinx-rtd-theme python3-pip build-essential
Création d'un nouveau projet
----------------------------
On commence par se placer dans notre dossier html, et on initialise le projet :
.. code-block:: bash
cd /var/www/html
sphinx-quickstart
Et on répond aux questions posées :
.. code-block::
:emphasize-lines: 11,14,15,16,24
Welcome to the Sphinx 4.2.0 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Selected root path: .
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y
The project name will occur in several places in the built documentation.
> Project name: Unixyourbrain Documentation
> Author name(s): beastie
> Project release []: 0.1
If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.
For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: fr
Creating file /var/www/test/source/conf.py.
Creating file /var/www/test/source/index.rst.
Creating file /var/www/test/Makefile.
Creating file /var/www/test/make.bat.
Finished: An initial directory structure has been created.
You should now populate your master file /var/www/test/source/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
Sphinx nous a automatiquement créé un dossier source dans lequel sera organisé notre documentation.
Il créer aussi un Makefile pour générer le site. Dans le dossier source, on retrouve deux fichiers
qui vont nous intéresser, le fichier conf.py, qui contient la configuration propre à sphinx, et
un fichier index.rst qui sera le point d'entrée de notre documentation.
Configuration du thème ReadTheDocs
----------------------------------
dans le fichier ``source/conf.py`` il faut modifier le paramètre ``html_theme``
.. code-block:: python
html_theme = 'sphinx_rtd_theme'
on peut aussi ajouter quelques options pour plus de confort
.. code-block:: python
html_theme_options = {
'collapse_navigation': False,
'prev_next_buttons_location': 'both',
}
Les options du thème sont documentées
`ici `_
Modification du CSS
-------------------
Le thème readthedocs ne propose pas les blocs de code sur fond sombre. Heureusement,
sphinx nous permet de rajouter du css et du javascript personnalisé. Pour ça, on créer le fichier
``source/_static/css/custom.css``. On y ajoute les lignes suivantes :
.. code-block:: css
.rst-content pre.literal-block, .rst-content div[class^="highlight"] {
background: #212121;
color: #fff;
border: 1px solid #3a3a3a;
}
.rst-content div.highlight span.linenos {
border-right: 1px solid #3a3a3a;
}
.rst-content div[class^="highlight"] pre .hll {
background-color: #13533b;
}
Une fois le CSS créé, il faut le renseigner dans la configuration de sphinx.
On édite le fichier ``soucre/conf.py`` et on ajoute après les lignes 3 à 5 après le
paramètre ``html_static_path``
.. code-block:: python
html_static_path = ['_static']
html_css_files = [
'css/custom.css',
]
Si vous modifiez le CSS après avoir lancé un liveserveur, celui ci ne sera pas automatiquement
pris en compte. Il faudra supprimer le dossier ``_build``.
(cf. `Utilisation d'un liveserveur <#utilisation-d-un-liveserveur>`__)
Utilisation d'un liveserveur
----------------------------
Pour faclilter l'édition de la documentation, sphinx nous fournit le paquet
``python3-sphinx-autobuild``. Dans le dossier ``/var/www/html``,
il suffit de lancer la commande suivante :
.. code-block:: bash
sphinx-autobuild source/ _build/
On peut désormais se connecter à l'adresse suivante : ``_. À chaque sauvegarde
d'un fichier de documentation, le liveserveur va régénérer les fichiers html, et recharger
la page automatiquement.
.. attention::
le liveserveur ne régénère pas automatiquement le menu. lors d'un changement dans le
menu il faut supprimer notre dossier _build
.. code-block:: bash
rm -fr _build
Compilation et mise en ligne
----------------------------
Pour mettre en ligne notre documentation, il faut d'abbord générer l'arborescence
html à l'aide de sphinx. On le fait à l'aide de la commande make fournie par
le paquet build-essential.
.. code-block:: bash
make html
Sphinx créer un dossier build pour générer la documentation.
on retrouve dans ce dossier un dossier html contenant le site de notre documentation.
C'est ce dossier que l'on va présenter comme racine du site web.
Pour le mettre en ligne, il suffit de configurer un vhost apache avec la configuration
suivante :
.. code-block:: apacheconf
ServerAdmin webmaster@localhost
DocumentRoot /var/www/html/build/html
Options -Indexes -FollowSymLinks
AllowOverride none
Require all granted
ErrorLog ${APACHE_LOG_DIR}/error.log
CustomLog ${APACHE_LOG_DIR}/access.log combined
Création d'un venv
------------------
.. note::
Depuis peu on ne peut plus unstaller des paquets avec pip en global sur notre
distribution, il va donc falloir créer un environnement virtuel python.
.. code-block:: bash
:linenos:
python -m venv .venv
source .venv/bin/activate
pip install sphinx_rtd_theme
Prise en charge du format MarkDown
----------------------------------
Pour interpréter le MarkDown, Sphinx utilise la librairie python `MyST `_
On l'installe à partir du gestionnaire de paquets python `pip `_
.. code-block:: bash
pip install --upgrade myst-parser
On ajoute ensuite les lignes suivantes dans ``soucre/conf.py``
.. code-block:: python
extensions = [
'myst_parser'
]
source_suffix = {
'.rst': 'restructuredtext',
'.txt': 'markdown',
'.md': 'markdown',
}
Ajout su support pour les emoji
-------------------------------
Pour ça il faut unstaller le package python ``sphinxemoji``
.. code-block:: bash
pip install --upgrade sphinxemoji
On configure ensuite sphinx afin qu'il utilise l'extension :
.. code-block:: python
extensions = [
'sphinxemoji.sphinxemoji',
]
.. warning::
Ce module n'est pas compatible avec ``sphinx-autobuild``, il faut
donc désactiver cette option dans la configuration pour pouvoir
utiliser le live serveur.
Voilà, c'est fini, vous trouverez toutes les emoji et toutes les explications `ici `_ |:smile:|