Sphinx Autodoc ist nicht automatisch genug

Ich versuche, mit Sphinx ein Projekt mit mehr als 5.000 Zeilen in Python zu dokumentieren. Es hat ungefähr 7 Basismodule. Soweit ich weiß, muss ich für die Verwendung von Autodoc für jede Datei in meinem Projekt folgenden Code schreiben:

.. automodule:: mods.set.tests
    :members:
    :show-inheritance:

Das ist viel zu langweilig, weil ich viele Dateien habe. Es wäre viel einfacher, wenn ich nur angeben könnte, dass das 'Mods'-Paket dokumentiert werden soll. Sphinx könnte dann rekursiv das Paket durchgehen und eine Seite für jedes Submodul erstellen.

Gibt es eine solche Funktion? Wenn nicht, könnte ich ein Skript schreiben, um alle ersten Dateien zu erstellen, aber das würde viel Zeit in Anspruch nehmen.

Sie können dieses Skript überprüfen , das ich erstellt habe. Ich denke, es kann dir helfen.

Dieses Skript analysiert einen Verzeichnisbaum, der nach Python-Modulen und -Paketen sucht, und erstellt ReST-Dateien entsprechend, um eine Codedokumentation mit Sphinx zu erstellen. Außerdem wird ein Modulindex erstellt.

AKTUALISIEREN

Dieses Skript ist jetzt Teil von Sphinx 1.1 als Apidoc .

Ich weiß nicht, ob Sphinx autosummaryzum Zeitpunkt der ursprünglichen Frage eine Erweiterung hatte, aber im Moment ist es durchaus möglich, eine solche automatische Generierung ohne Verwendung eines sphinx-apidocähnlichen Skripts einzurichten . Unten finden Sie Einstellungen, die für eines meiner Projekte funktionieren.

1. Aktivieren Sie die autosummaryErweiterung (sowie autodoc) in der conf.pyDatei und setzen Sie die autosummary_generateOption auf True. Dies kann ausreichen, wenn Sie keine benutzerdefinierten *.rstVorlagen verwenden. Fügen Sie andernfalls Ihr Vorlagenverzeichnis hinzu, um die Liste auszuschließen, oder autosummaryversuchen Sie, sie als Eingabedateien zu behandeln (was ein Fehler zu sein scheint).

   extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary']
   autosummary_generate = True
   templates_path = [ '_templates' ]
   exclude_patterns = ['_build', '_templates']

2. Verwendung autosummary::im Inhaltsverzeichnisbaum in Ihrer index.rstDatei. In diesem Beispiel Dokumentation für Module project.module1und project.module2wird automatisch generiert und in platziert _autosummaryVerzeichnis.

   PROJECT
   =======
   
   .. toctree::
   
   .. autosummary::
      :toctree: _autosummary
   
      project.module1
      project.module2

3. Standardmäßig autosummarywerden nur sehr kurze Zusammenfassungen für Module und ihre Funktionen generiert. Um dies zu ändern, können Sie eine benutzerdefinierte Vorlagendatei einfügen_templates/autosummary/module.rst (die mit Jinja2 analysiert wird ):

   {{ fullname }}
   {{ underline }}
   
   .. automodule:: {{ fullname }}
       :members:

Zusammenfassend ist es nicht erforderlich, das _autosummaryVerzeichnis unter Versionskontrolle zu halten . Sie können es auch beliebig benennen und an einer beliebigen Stelle im Quellbaum platzieren (das Platzieren unten _buildfunktioniert jedoch nicht).

In jedem Paket kann die __init__.pyDatei .. automodule:: package.moduleKomponenten für jeden Teil des Pakets enthalten.

Dann können Sie .. automodule:: packageund es macht meistens, was Sie wollen.

Ab Sphinx Version 3.1 (Juni 2020) hat sphinx.ext.autosummary(endlich!) Rekursion.

Sie müssen also keine Modulnamen mehr fest codieren oder sich für die automatische Paketerkennung auf Bibliotheken von Drittanbietern wie Sphinx AutoAPI oder Sphinx AutoPackageSummary verlassen .

Beispiel für ein zu dokumentierendes Python 3.7-Paket ( siehe Code in Github und Ergebnis in ReadTheDocs ):

mytoolbox
|-- mypackage
|   |-- __init__.py
|   |-- foo.py
|   |-- mysubpackage
|       |-- __init__.py
|       |-- bar.py
|-- doc
|   |-- source
|       |--index.rst
|       |--conf.py
|       |-- _templates
|           |-- custom-module-template.rst
|           |-- custom-class-template.rst

conf.py::

import os
import sys
sys.path.insert(0, os.path.abspath('../..'))  # Source code dir relative to this file

extensions = [
    'sphinx.ext.autodoc',  # Core library for html generation from docstrings
    'sphinx.ext.autosummary',  # Create neat summary tables
]
autosummary_generate = True  # Turn on sphinx.ext.autosummary

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

index.rst(Neue :recursive:Option beachten ):

Welcome to My Toolbox
=====================

Some words.

.. autosummary::
   :toctree: _autosummary
   :template: custom-module-template.rst
   :recursive:

   mypackage

Dies reicht aus, um jedes Modul im Paket automatisch zusammenzufassen, auch wenn es tief verschachtelt ist. Für jedes Modul werden dann alle Attribute, Funktionen, Klassen und Ausnahmen in diesem Modul zusammengefasst.

Seltsamerweise sphinx.ext.autosummarygenerieren die Standardvorlagen jedoch keine separaten Dokumentationsseiten für jedes Attribut, jede Funktion, jede Klasse und jede Ausnahme und verknüpfen sie aus den Übersichtstabellen. Es ist möglich, die Vorlagen zu erweitern, um dies zu tun, wie unten gezeigt, aber ich kann nicht verstehen, warum dies nicht das Standardverhalten ist - sicherlich ist es das, was die meisten Leute wollen würden ..? Ich habe es als Feature-Anfrage angesprochen .

Ich musste die Standardvorlagen lokal kopieren und dann hinzufügen:

• Kopieren site-packages/sphinx/ext/autosummary/templates/autosummary/module.rstnachmytoolbox/doc/source/_templates/custom-module-template.rst
• Kopieren site-packages/sphinx/ext/autosummary/templates/autosummary/class.rstnachmytoolbox/doc/source/_templates/custom-class-template.rst

Der Haken in custom-module-template.rstist index.rstoben mit der :template:Option. (Löschen Sie diese Zeile, um zu sehen, was mit den Standardvorlagen für Site-Pakete geschieht.)

custom-module-template.rst (zusätzliche Zeilen rechts):

{{ fullname | escape | underline}}

.. automodule:: {{ fullname }}
  
   {% block attributes %}
   {% if attributes %}
   .. rubric:: Module Attributes

   .. autosummary::
      :toctree:                                          <-- add this line
   {% for item in attributes %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block functions %}
   {% if functions %}
   .. rubric:: {{ _('Functions') }}

   .. autosummary::
      :toctree:                                          <-- add this line
   {% for item in functions %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block classes %}
   {% if classes %}
   .. rubric:: {{ _('Classes') }}

   .. autosummary::
      :toctree:                                          <-- add this line
      :template: custom-class-template.rst               <-- add this line
   {% for item in classes %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block exceptions %}
   {% if exceptions %}
   .. rubric:: {{ _('Exceptions') }}

   .. autosummary::
      :toctree:                                          <-- add this line
   {% for item in exceptions %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

{% block modules %}
{% if modules %}
.. rubric:: Modules

.. autosummary::
   :toctree:
   :template: custom-module-template.rst                 <-- add this line
   :recursive:
{% for item in modules %}
   {{ item }}
{%- endfor %}
{% endif %}
{% endblock %}

custom-class-template.rst (zusätzliche Zeilen rechts):

{{ fullname | escape | underline}}

.. currentmodule:: {{ module }}

.. autoclass:: {{ objname }}
   :members:                                    <-- add at least this line
   :show-inheritance:                           <-- plus I want to show inheritance...
   :inherited-members:                          <-- ...and inherited members too

   {% block methods %}
   .. automethod:: __init__

   {% if methods %}
   .. rubric:: {{ _('Methods') }}

   .. autosummary::
   {% for item in methods %}
      ~{{ name }}.{{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block attributes %}
   {% if attributes %}
   .. rubric:: {{ _('Attributes') }}

   .. autosummary::
   {% for item in attributes %}
      ~{{ name }}.{{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

Sphinx AutoAPI macht genau das.

Vielleicht suchen Sie nach Epydoc und dieser Sphinx-Erweiterung .