Restart repo

2023-12-30 22:30:42 +01:00
commit 1c4278a3d8
37 changed files with 3019 additions and 0 deletions
--- a/sphinx/documentation.rst
+++ b/sphinx/documentation.rst
@@ -0,0 +1,21 @@
+..
+  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".
+
+Création et organisation de la documentation
+============================================
+
+L'arborescence de notre documentation se fera directement dans les fichiers index.rst via 
+l'attribut ``.. toctree::``
+
+Les différents attributs pour ce bloc sont documentés ici : `Directives toctree <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html>`_
+Je vous conseille de faire un tour sur ce lien qui vous montre toutes les spécificités de ce que peut inclure sphinx dans votre documentation grace
+à la syntaxe rst.
+
+J'utilise notament la directive :hidden dans mon indec pour ne pas que le bloc toctree s'affiche sur la page mais soit bien pris en compte par le menu
+
--- a/sphinx/index.rst
+++ b/sphinx/index.rst
@@ -0,0 +1,18 @@
+..
+  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".
+
+La documentation avec Sphinx
+============================
+
+.. toctree::
+  :maxdepth: 2
+
+  installation.rst
+  documentation.rst
+  syntax.rst
--- a/sphinx/installation.rst
+++ b/sphinx/installation.rst
@@ -0,0 +1,270 @@
+..
+  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:|
--- a/sphinx/syntax.rst
+++ b/sphinx/syntax.rst
@@ -0,0 +1,214 @@
+..
+  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".
+
+La syntaxe reStructuredText
+===========================
+
+Les titres
+----------
+
+Les liens
+---------
+
+.. code-block:: rst
+
+  `ReSrtucturedText <https://docutils.sourceforge.io/rst.html>`_ 
+
+Resultat :
+
+`ReSrtucturedText <https://docutils.sourceforge.io/rst.html>`_ 
+
+Les listes
+----------
+
+.. code-block:: rst
+
+  Bullet lists:
+
+    - This is item 1
+    - This is item 2 
+
+Resultat :
+
+Bullet lists:
+
+- This is item 1
+- This is item 2 
+
+.. code-block:: rst
+
+  Enumerated lists:
+
+  3. This is the first item
+  4. This is the second item
+  #. Auto ennumerated item
+
+Resultat :
+
+Enumerated lists:
+
+3. This is the first item
+4. This is the second item
+#. Auto ennumerated item
+
+Plus d'infos `ici <https://docutils.sourceforge.io/docs/user/rst/quickref.html#bullet-lists>`_.
+
+Les blocs
+---------
+
+.. code-block:: rst 
+
+  .. error:: text
+
+Resultat :
+
+.. error:: text
+
+.. code-block:: rst 
+
+  .. warning:: text
+
+Resultat :
+
+.. warning:: text
+
+.. code-block:: rst 
+
+  .. note:: text
+
+Resultat :
+
+.. note:: text
+
+.. code-block:: rst 
+
+  .. tip:: text
+
+Resultat :
+
+.. tip:: text
+
+.. code-block:: rst 
+
+  .. important:: text
+
+Resultat :
+
+.. important:: text
+
+Les Maths
+---------
+
+.. code-block:: rst
+
+  .. math::
+    (a + b)^2 = a^2 + 2ab + b^2 \\
+              = a^2 - 2ab + b^2
+
+Resultat :
+
+.. math::
+  (a + b)^2 = a^2 + 2ab + b^2 \\
+            = a^2 - 2ab + b^2
+
+Plus d'infos sur ce bloc  `ici <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#math>`_.
+
+Le code
+-------
+
+analysé avec la librairie `Pygments <https://pygments.org/>`_. Pour en 
+savoir plus sur son utilisation et les langages supportés, c'est `ici <https://pygments.org/languages/>`_
+
+Code "inline"
+~~~~~~~~~~~~~
+
+Le code "inline" est un génère un objet html <inline> qui s'intègre dans le texte comme ``ceci``
+
+.. code-block:: rst
+
+  ``code``
+
+Resultat :
+
+``code``
+
+Code "block"
+~~~~~~~~~~~~
+
+Le code "block" génère un bojet html <block>. La syntaxe rst est la suivante :
+
+.. code-block:: rst
+
+  .. code-block:: bash
+    :linenos:
+    :lineno-start: 5
+    :caption: caption
+    :name: a label
+    :emphasize-lines: 2,6
+
+    #!/bin/bash
+    function start() {
+      while :
+      do
+        discord --no-sandbox $1
+      done
+    }
+
+.. code-block:: bash
+  :linenos:
+  :lineno-start: 5
+  :caption: a caption
+  :name: a label
+  :emphasize-lines: 2,6
+
+  #!/bin/bash
+  function start() {
+    while :
+    do
+      discord --no-sandbox $1
+    done
+  }
+
+| Les paramètres ne sont pas très compliqués :
+| ``:lineos:`` : affiche les numéros de ligne
+| ``:linestart: number`` : affiche les numéros de ligne
+| ``:caption: string`` : affiche un titre au bloc de code
+| ``:name: string`` : ???
+| ``:emphasize-lines: number list coma separated`` : met en surbrillance les lignes renseignées par cette option
+
+Inclure un fichier de Code
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On peut avec Sphinx inclure un fichier de code dans in bloc.
+Ici, j'inclus le code de cette page dans un bloc de code rst
+
+.. code-block:: rst
+
+  .. literalinclude:: syntax.rst
+    :language: rst
+
+Resultat :
+
+.. literalinclude:: syntax.rst
+  :language: rst
+
+Les images
+----------
+
+.. code-block:: rst
+
+  .. image:: ../images/example_image.png
+    :width: 400
+    :alt: Alternative text
+
+Resultat :
+
+.. image:: ../images/example_image.png
+  :width: 400
+  :alt: Alternative text