Comment utiliser l'autodoc de Sphinx pour documenter la méthode __init__(self) d'une classe ?

Question

Sphinx ne génère pas de documentation pour __init__(self) par défaut. J'ai essayé ce qui suit :

.. automodule:: mymodule
    :members:

et

..autoclass:: MyClass
    :members:

Dans le fichier conf.py, la configuration suivante ajoute uniquement la docstring __init__(self) à la docstring de la classe ( la documentation autodoc de Sphinx semble convenir que c'est le comportement attendu, mais ne mentionne rien concernant le problème que j'essaie de résoudre) :

autoclass_content = 'both'

Answer 1

Voici trois alternatives :

1. Pour garantir que __init__() est toujours documenté, vous pouvez utiliser autodoc-skip-member dans le fichier conf.py. Comme ceci :

   def skip(app, what, name, obj, would_skip, options):
       if name == "__init__":
           return False
       return would_skip
   
   def setup(app):
       app.connect("autodoc-skip-member", skip)

   Cela définit explicitement __init__ ne doit pas être ignoré (ce qui est le cas par défaut). Cette configuration n'est spécifiée qu'une seule fois et ne nécessite pas de balisage supplémentaire pour chaque classe du fichier source .rst.

2. Le site special-members l'option était ajouté dans Sphinx 1.1 . Il fait des membres "spéciaux" (ceux qui ont des noms comme __special__ ) soit documenté par autodoc.

   Depuis Sphinx 1.2, cette option prend des arguments, ce qui la rend plus utile qu'auparavant.

3. Utilisez automethod :

   .. autoclass:: MyClass     
      :members: 
   
      .. automethod:: __init__

   Ceci doit être ajouté pour chaque classe (ne peut pas être utilisé avec l'option automodule (comme indiqué dans un commentaire de la première révision de cette réponse).

Answer 2

Vous étiez proche. Vous pouvez utiliser le autoclass_content dans votre conf.py fichier :

autoclass_content = 'both'

Answer 3

Même s'il s'agit d'un article plus ancien, pour ceux qui le consultent actuellement, il existe également une autre solution introduite dans la version 1.8. Selon le documentation Vous pouvez ajouter le special-member dans les options autodoc_default_options de votre conf.py .

Exemple :

autodoc_default_options = {
    'members': True,
    'member-order': 'bysource',
    'special-members': '__init__',
    'undoc-members': True,
    'exclude-members': '__weakref__'
}

Answer 4

Au cours des dernières années, j'ai écrit plusieurs variantes de autodoc-skip-member pour divers projets Python sans rapport, car je voulais des méthodes comme __init__() , __enter__() et __exit__() pour apparaître dans ma documentation API (après tout, ces "méthodes spéciales" font partie de l'API et quel meilleur endroit pour les documenter que dans la docstring de la méthode spéciale).

Récemment, j'ai pris la meilleure implémentation et l'ai intégrée à l'un de mes projets Python ( voici la documentation ). La mise en œuvre se résume à ça :

import types

def setup(app):
    """Enable Sphinx customizations."""
    enable_special_methods(app)

def enable_special_methods(app):
    """
    Enable documenting "special methods" using the autodoc_ extension.

    :param app: The Sphinx application object.

    This function connects the :func:`special_methods_callback()` function to
    ``autodoc-skip-member`` events.

    .. _autodoc: http://www.sphinx-doc.org/en/stable/ext/autodoc.html
    """
    app.connect('autodoc-skip-member', special_methods_callback)

def special_methods_callback(app, what, name, obj, skip, options):
    """
    Enable documenting "special methods" using the autodoc_ extension.

    Refer to :func:`enable_special_methods()` to enable the use of this
    function (you probably don't want to call
    :func:`special_methods_callback()` directly).

    This function implements a callback for ``autodoc-skip-member`` events to
    include documented "special methods" (method names with two leading and two
    trailing underscores) in your documentation. The result is similar to the
    use of the ``special-members`` flag with one big difference: Special
    methods are included but other types of members are ignored. This means
    that attributes like ``__weakref__`` will always be ignored (this was my
    main annoyance with the ``special-members`` flag).

    The parameters expected by this function are those defined for Sphinx event
    callback functions (i.e. I'm not going to document them here :-).
    """
    if getattr(obj, '__doc__', None) and isinstance(obj, (types.FunctionType, types.MethodType)):
        return False
    else:
        return skip

Oui, il y a plus de documentation que de logique :-). L'avantage de définir un autodoc-skip-member comme ceci par rapport à l'utilisation de la fonction special-members option (pour moi) est que le special-members permet également de documenter des propriétés telles que __weakref__ (disponible sur toutes les classes du nouveau style, AFAIK) que je considère comme du bruit et pas du tout utile. L'approche callback évite cela (car elle ne fonctionne que sur les fonctions/méthodes et ignore les autres attributs).

Answer 5

Tant que cette commission est approuvée : https://github.com/sphinx-doc/sphinx/pull/9154 Dans la prochaine version de sphinx (>4.1.2), il sera possible de.. :

..autoclass:: MyClass1
    :members:
    :class-doc-from: "class"

..autoclass:: MyClass2
    :members:
    :class-doc-from: "init"