ReST
https://rest-sphinx-memo.readthedocs.io/en/latest/

Syntax

code

module,class,method

:var <TYPE> <NOM>: <Description de la variabl>
:var <NOM>: <Description de la variabl>

:param <TYPE> <NOM>: <Description du paramètre>.
:param <NOM>: <Description d'un autre paramètre. Ici on ne précise pas le type, c'est optionnel>.

:returns: <Description de ce qui est retourné (si la fonction retourne quelque chose)>.
:rtype: <Type de ce qui est retourné>

:raises <Exception>: <Description de l'exception>.

:myindex: (int): deep

reference

`link vers ce siteb <https://code.ambau.ovh/>`_

:class:`mymodule.MyClass` About my class.
:meth:`mymodule.MyClass.myfunction` And my cool function

format

*italique*
**gras**

`code inline``

directives

https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

.. NOTE:: Ceci est une note.
.. WARNING:: Ceci est un avertissement !
.. IMPORTANT:: Ceci est important 
.. TODO:: Liste de choses à faire

.. IMAGE:: files/graph1.png # from source path & html path

title

Titre principal
===============

Titre de niveau 2   
-----------------

Titre de niveau 3
~~~~~~~~~~~~~~~~~

Un autre titre de niveau 2
--------------------------

list

* Ceci est une liste
* un autre élément

  * Une sous-liste
  * notez bien le saut de ligne avec la liste principale,
    ça ne marchera pas si vous l'oubliez !

* un dernier élément

1. Un
2. Deux
3. Troishttps://rest-sphinx-memo.readthedocs.io/en/latest/ReST.html

#. Un
#. Deux
#. Trois

table

+-----------+-----------+-----------+
| Heading 1 | Heading 2 | Heading 3 |
+===========+===========+===========+
| Hello     | World     |           |
+-----------+-----------+-----------+
| foo       |                       |
+-----------+          bar          |
| baz       |                       |
+-----------+-----------------------+

rst files

index.rst

TITLE 1
=======

.. toctree::
    :maxdepth: 2
    :caption: Contents:

    ./AMatrix.rst

name.rst

include

include:: ../README.rst

module

.. module:: parrot
   :platform: Unix, Windows
   :synopsis: Analyze and reanimate dead parrots.
.. moduleauthor:: Eric Cleese <eric@python.invalid>
.. moduleauthor:: John Idle <john@python.invalid>

auto

.. automodule:: package.module # or just .. automodule:: module
.. autoclass:: classname
.. autofunction:: functionname
.. automethod:: myproject.foomodule.Foo.__contains__

options

    :show-inheritance:
    :members:
    :private-members:
    :undoc-members:
    :special-members:
    :exclude-members: __doc__

examples

.. automodule:: modulename
    :members:
    :undoc-members:
    :exclude-members: __dict__,__weakref__

Installation

# manjaro
yay -S python-sphinx python-sphinx_rtd_theme

Use

https://deusyss.developpez.com/tutoriels/Python/SphinxDoc/

https://blog.flozz.fr/2020/09/07/introduction-a-sphinx-un-outil-de-documentation-puissant/
https://romanvm.pythonanywhere.com/post/autodocumenting-your-python-code-sphinx-part-i-5/
https://samnicholls.net/2016/06/15/how-to-sphinx-readthedocs/

sphinx-quickstart

Go to your project path

cd $path2myproject
mkdir docs && cd docs
sphinx-quickstart
export PYTHONPATH=$path2myproject
make html

sphinx-apidoc

sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN …]

Configuration

cd $path2myproject
file="source/conf.py"
sed -i "s|.*\(import os\)$|\1|" "${file}"
sed -i "s|.*\(import sys\)$|\1|" "${file}"
sed -i "s|.*sys.path.insert.*|sys.path.insert(0, os.path.abspath('../../'))|" "${file}"
sed -i "s|^\(extensions = [.*\)$|\1\n\t'sphinx.ext.autodoc',|" "${file}"
sed -i "s|^\(extensions = [.*\)$|\1\n\t'sphinx_rtd_theme',|" "${file}"
sed -i "s|^\(html_theme = .*\)$|\1\nhtml_theme = 'sphinx_rtd_theme'|" "${file}"
make html

conf.py

path

import os
import sys
# sys.path.insert(0, os.path.abspath('.'))
sys.path.insert(0, os.path.abspath('../../'))

extensions

extensions = [
    'sphinx.ext.autodoc',
    'sphinx_rtd_theme',
    'sphinx.ext.todo',
    'sphinx.ext.autosummary',
    'sphinx_autopackagesummary',
]

[extensions]
todo_include_todos=True
#autosummary_generate = True
autodoc_member_order = 'bysource' # alphabetical (alphabetical), groupwise(member type), bysource (source order)