web-dev-qa-db-fra.com

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

Sphinx ne génère pas de documents pour __init __ (auto) par défaut. J'ai essayé ce qui suit:

.. automodule:: mymodule
    :members:

et

..autoclass:: MyClass
    :members:

Dans conf.py, la définition de ce qui suit n'ajoute que la docstring __init __ (self) à la classe docstring ( la documentation d'autodoc Sphinx semble convenir qu'il s'agit du comportement attendu, mais ne mentionne rien concernant le problème que je '' m essayant de résoudre):

autoclass_content = 'both'
pythonpython-sphinxautodoc
85
Jacob Marble

Voici trois alternatives:

  1. Pour vous assurer que __init__() est toujours documenté, vous pouvez utiliser autodoc-skip-member dans conf.py. Comme ça:

    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 pas ignorer (ce qui est par défaut). Cette configuration est spécifiée une fois et ne nécessite aucun balisage supplémentaire pour chaque classe de la source .rst.

  2. Le special-members était ajoutée dans Sphinx 1.1 . Il fait des membres "spéciaux" (ceux avec des noms comme __special__) être documenté par autodoc.

    Depuis Sphinx 1.2, cette option prend des arguments qui la rendent plus utile qu'elle ne l'était auparavant.

  3. Utilisez automethod:

    .. autoclass:: MyClass     
   :members: 

   .. automethod:: __init__

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

94
mzjn

Tu étais proche. Vous pouvez utiliser le autoclass_content option dans votre conf.py fichier:

autoclass_content = 'both'
55
gotgenes

Au cours des dernières années, j'ai écrit plusieurs variantes de rappels autodoc-skip-member Pour divers projets non liés Python parce que 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 ). L'implémentation revient essentiellement pour ça:

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 rappel autodoc-skip-member Comme celui-ci par rapport à l'utilisation de l'option special-members (Pour moi) est que l'option special-members Permet également de documenter des propriétés comme __weakref__ (disponible sur toutes les classes de nouveau style, AFAIK) que je considère comme du bruit et pas du tout utile. L'approche de rappel évite cela (car elle ne fonctionne que sur les fonctions/méthodes et ignore les autres attributs).

4
xolox