271 lines
8.4 KiB
ReStructuredText
271 lines
8.4 KiB
ReStructuredText
..
|
|
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 <https://www.sphinx-doc.org/fr/master/>`_ est un framework écrit en `Python <https://www.python.org/>`_
|
|
qui va parser notre documentation dans la syntaxe `ReSrtucturedText <https://docutils.sourceforge.io/rst.html>`_
|
|
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 <https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html>`_
|
|
|
|
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 : `<http://127.0.0.1:8000>`_. À 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
|
|
|
|
<VirtualHost *:80>
|
|
ServerAdmin webmaster@localhost
|
|
DocumentRoot /var/www/html/build/html
|
|
|
|
<Directory /var/www/html/build/html/>
|
|
Options -Indexes -FollowSymLinks
|
|
AllowOverride none
|
|
Require all granted
|
|
</Directory>
|
|
|
|
ErrorLog ${APACHE_LOG_DIR}/error.log
|
|
CustomLog ${APACHE_LOG_DIR}/access.log combined
|
|
</VirtualHost>
|
|
|
|
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 <https://myst-parser.readthedocs.io/en/latest/>`_
|
|
On l'installe à partir du gestionnaire de paquets python `pip <http://link>`_
|
|
|
|
.. 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 <https://sphinxemojicodes.readthedocs.io/en/stable/>`_ |:smile:|
|