Cahier Bleu à Paulo

Quelques ligne sur Sphinx-doc  et le langage ReST:
Sphinx est un utilitaire python permettant de générer de la doc
- https://deusyss.developpez.com/tutoriels/Python/SphinxDoc/
- http://sphinx-doc.org/

• installation simple avec pip
  nb : install de pip par dnf
  

  # si la commande pip (pip3) n'est pas installée
  sudo dnf install pip
  
  # installation de sphinx
  sudo pip install --user sphinx

• si problème avec le plugin 'sphinxcontrib-plantum':

  # install du plugin
  pip3 --proxy http://proxy:3128 install sphinxcontrib-plantuml
  
  # install du thème
  pip3 --proxy http://proxy:3128 install sphinx_rtd_theme

   

• création du repertoire qui contiendra la doc et génération arbo

  # création repertoire de travail
  mkdir ~/ma_super_doc && cd ~/ma_super_doc
  
  # génération arbo
  sphinx-quickstart

• configuration <conf.py>

  # -*- coding: utf-8 -*-
  
  import os, subprocess
  
  # -- Project information -----------------------------------------------------
  project = u'Projet Foo'
  copyright = u'2020, World Compagny'
  author = u'Moa'
  
  # Version du projet via GIT
  release = subprocess.check_output(["git", "describe", "--tags", "--always"]) \
            .strip().decode('utf8')
  version = release.split('-', 2)[0]
  
   -- General configuration ---------------------------------------------------
  # Add any Sphinx extension module names here, as strings. They can be
  # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
  # ones.
  extensions = [
  ]
  # Add any paths that contain templates here, relative to this directory.
  templates_path = ['_templates']
  
  # The language for content autogenerated by Sphinx. Refer to documentation
  # for a list of supported languages.
  #
  # This is also used if you do content translation via gettext catalogs.
  # Usually you set "language" from the command line for these cases.
  language = 'fr'
  
  # List of patterns, relative to source directory, that match files and
  # directories to ignore when looking for source files.
  # This pattern also affects html_static_path and html_extra_path.
  exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
  
  # -- Options for HTML output -------------------------------------------------
  # The theme to use for HTML and HTML Help pages.  See the documentation for
  # a list of builtin themes.
  #
  # html_theme = 'alabaster'
  html_theme = 'sphinx_rtd_theme'
  
  # Add any paths that contain custom static files (such as style sheets) here,
  # relative to this directory. They are copied after the builtin static files,
  # so a file named "default.css" will overwrite the builtin "default.css".
  html_static_path = ['_static']
  
  # These paths are either relative to html_static_path
  # or fully qualified paths (eg. https://...)
  html_css_files = [
      'css/custom.css',
  ]

• modification css du theme <_static/css/custom.css>

  html_css_files = [
      'css/custom.css',
  ]

  Surcharge du css : 

  [foo@foo css]$ cat custom.css
  
  /* CSS for local development */
  a.reference.internal.current {
      margin-left: 200px;
  }
  /* override table width restrictions */
  .wy-table-responsive table td, .wy-table-responsive table th {
      white-space: normal;
  }
  /* override line-break indentation */
  table.docutils div.line-block {
      margin-left: 0;
  }
  /* remove page width restriction */
  .wy-nav-content {
      max-width: 80%;
  }

• fichier index.rst (à la racine du reperoire)
  nb : les fichiers de doc sont dans le repertoire source
   

  [foo@foo ex2]$ cat index.rst
  
  Documentation du framework de Foo
  =================================
  
  Principe
  --------
  
  Ce framework ne sert à rien et c'est pour ça qu'il est indispensable
  
  Fonctionnement
  --------------
  
  Un serveur de Foo sur OpenNebula avec les paramètres
  suivants :
  
  - commit/branch/tag valide du git foo-server-conf
  - commit/branch/tag valide du git foo-conf
  - réseau OpenNebula dans lequel le serveur de déploiement doit faire le
    foo (DHCP / PxE)
  
  .. toctree::
      :maxdepth: 1
      :caption: Introduction
                    
      source/introduction/index
  
  .. toctree::
      :maxdepth: 1
      :caption: Difference
      
      source/difference/index
  
  .. toctree::
      :maxdepth: 1
      :caption: Migration
      
      source/migration/index
  
  .. toctree::
      :maxdepth: 1
      :caption: Performances
      
      source/performance/index