Sphinx-Dokumentation schreiben

Unter anderem für Zope-Interfaces und Archetypes Schemate gibt es Zusatzprodukte, die das Schreiben von Sphinx-Dokumentation vereinfachen.

Allgemein

Für das Schreiben von Dokumentationen mit Sphinx können Sie sich den reStructuredText Primer oder das 1. Restructured Text (reST) and Sphinx CheatSheet anschauen.

Zope Interfaces

repoze.sphinx.autointerface erlaubt die Generierung aus Zope Interfaces. Es kann einfach installiert werden mit:

$ easy_install repoze.sphinx.autointerface

Anschließend muss es noch in die èxtensions der conf.py-Datei eingetragen werden:

extensions = […
              'repoze.sphinx.autointerface',
             ]

Nun können die interface autodocs in die Dokumentation eingebunden werden mit:

.. autointerface:: vs.registration.interfaces.IRegistration

Die Ausgabe enthält dann:

  • den Interface-Namen

  • alle Basis-Interfaces

  • die doctstrings der Interfaces

  • die Methoden und Attribute der Interfaces

    Für jedes Attribut wird der Name und die Beschreibung angegeben

Archetypes-Schema

Zur Dokumentation des Schemas von Archetypes-Artikeltypen kann collective.sphinx.autoatschema verwendet werden.