Documenter semi-automatiquement

Sphinx est capable de trouver le fichier contenant le code-source de votre programme.

Documentation officielle

Pour récupérer les signatures et docstrings des fonctions avec l’extension autodoc, il faut modifier le fichier docs/source/conf.py.

Premièrement, indiquer le dossier où se trouve le fichier contenant les fonctions:

import os
import sys
sys.path.append('/home/....../docs/source')

Ensuite, charger l’extension autodoc:

extensions = [
  'sphinx.ext.autodoc'
]

Soit, docs/source/monProgramme.py:

ALPHA="abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
DIGIT="0123456789"
FILENAME=ALPHA+DIGIT+"-_" # nom de fichier sans extension

def input2(msg, str_carac=FILENAME, isCaracOK=True, isVideOK=False):
  """
  Cette fonction retourne une string composée de caractères autorisés.

 :param str msg: message affiché avant le curseur
 :param str str_carac: liste des caractères.
 :param bool isCaracOK: Indique que le second paramètre représente la liste des caractères autorisés (True, par défaut) ou la liste des caractères interdits (False)
 :param bool isVideOK: Indique que la valeur de retour peut être vide (True) ou pas (False,(par défaut)
 :return: Une string tapée (ou collée) par l'utilisateur
 :rtype: str
"""
  while(True):
    re=input(msg); OK=True
    for i in range(len(re)):
      if(isCaracOK):
        if (re[i] not in str_carac):
          print(re[i]+" est un caractère interdit."); OK=False; break
    else:
      if (re[i] in str_carac):
        print(re[i]+" est un caractère interdit."); OK=False; break
      if(not OK): continue
      if(not isVideOK and len(re)==0): continue
      return re

Si le fichier contenant les fonctions est monProgramme.py et que la fonction dont la docstring à récupérer est input2(…), alors dans le fichier d’extension .rst, il faut taper la directive:

.. autofunction:: monProgramme.input2

Ci-dessous, ce qui est rendu par cette directive :

monProgramme.input2(msg, str_carac='abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_', isCaracOK=True, isVideOK=False)

Cette fonction retourne une string composée de caractères autorisés.

Parameters

• msg (str) – message affiché avant le curseur

• str_carac (str) – liste des caractères.

• isCaracOK (bool) – Indique que le second paramètre représente la liste des caractères autorisés (True, par défaut) ou la liste des caractères interdits (False)

• isVideOK (bool) – Indique que la valeur de retour peut être vide (True) ou pas (False,(par défaut)

Returns

Une string tapée (ou collée) par l’utilisateur

Return type

str

Pour chaque fonction, il faut donc taper une directive.

Warning

Le point d’entrée de monProgramme.py doit être conditionel:

if __name__ == '__main__': main()

Documenter automatiquement