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