Wie dokumentiere ich mit Sphinxs Autodoc die __init __ (self) -Methode einer Klasse?

Sphinx generiert standardmäßig keine Dokumente für __init __ (self). Ich habe folgendes versucht:

.. automodule:: mymodule
    :members:

und

..autoclass:: MyClass
    :members:

Wenn Sie in conf.py Folgendes festlegen, wird nur die __init __ (selbst) docstring an die Klasse docstring angehängt ( die Sphinx-Autodoc-Dokumentation scheint zuzustimmen, dass dies das erwartete Verhalten ist, erwähnt jedoch nichts in Bezug auf das Problem, das ich zu lösen versuche):

autoclass_content = 'both'

Hier sind drei Alternativen:

1. Um sicherzustellen, dass dies __init__()immer dokumentiert ist, können Sie es autodoc-skip-memberin conf.py verwenden. So was:

   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)
   

   Dies definiert ausdrücklich, dass __init__nicht übersprungen werden soll (was standardmäßig der Fall ist). Diese Konfiguration wird einmal angegeben und erfordert kein zusätzliches Markup für jede Klasse in der ersten Quelle.

2. Die special-membersOption wurde in Sphinx 1.1 hinzugefügt . __special__Dadurch werden "spezielle" Mitglieder (solche mit Namen wie ) von autodoc dokumentiert.

   Seit Sphinx 1.2 verwendet diese Option Argumente, wodurch sie nützlicher ist als zuvor.

3. Verwendung automethod:

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

   Dies muss für jede Klasse hinzugefügt werden (kann nicht verwendet werden automodule, wie in einem Kommentar zur ersten Überarbeitung dieser Antwort ausgeführt).

Du warst nah. Sie können die autoclass_contentOption in Ihrer conf.pyDatei verwenden:

autoclass_content = 'both'

In den letzten Jahren habe ich mehrere Varianten geschrieben autodoc-skip-memberRückrufe für verschiedene unabhängige Python - Projekte , weil ich Methoden wollte wie __init__(), __enter__()und __exit__()in meiner API - Dokumentation zu zeigen (immerhin diese „spezielle Methoden“ sind Teil der API und was einen besseren Ort zu dokumentieren Sie sie als in der Dokumentzeichenfolge der speziellen Methode).

Kürzlich habe ich die beste Implementierung genommen und sie zu einem meiner Python-Projekte gemacht ( hier ist die Dokumentation ). Die Implementierung läuft im Wesentlichen auf Folgendes hinaus:

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

Ja, es gibt mehr Dokumentation als Logik :-). Der Vorteil der Definition eines autodoc-skip-membersolchen Rückrufs gegenüber der Verwendung der special-membersOption (für mich) besteht darin, dass die special-membersOption auch die Dokumentation von Eigenschaften wie __weakref__(verfügbar für alle Klassen neuen Stils, AFAIK) ermöglicht, die ich als Rauschen betrachte und die überhaupt nicht nützlich sind. Der Callback-Ansatz vermeidet dies (da er nur für Funktionen / Methoden funktioniert und andere Attribute ignoriert).

Obwohl dies ein älterer Beitrag ist, gibt es für diejenigen, die ihn ab sofort nachschlagen, auch eine andere Lösung, die in Version 1.8 eingeführt wurde. Gemäß der Dokumentation können Sie den special-memberSchlüssel in den autodoc_default_options zu Ihrem hinzufügen conf.py.

Beispiel:

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

Dies ist eine Variante, die nur enthält, __init__wenn sie Argumente enthält:

import inspect

def skip_init_without_args(app, what, name, obj, would_skip, options):
    if name == '__init__':
        func = getattr(obj, '__init__')
        spec = inspect.getfullargspec(func)
        return not spec.args and not spec.varargs and not spec.varkw and not spec.kwonlyargs
    return would_skip

def setup(app):
    app.connect("autodoc-skip-member", skip_init_without_args)