Wie dokumentiere ich Python-Pakete mit Sphinx

Question

Ich versuche, ein Paket in Python zu dokumentieren. Im Moment habe ich die folgende Verzeichnisstruktur:

. 
└── project 
    ├── _build 
    │   ├── doctrees 
    │   └── html 
    │    ├── _sources 
    │    └── _static 
    ├── conf.py 
    ├── index.rst 
    ├── __init__.py 
    ├── make.bat 
    ├── Makefile 
    ├── mod1 
    │   ├── foo.py 
    │   └── __init__.py 
    ├── mod2 
    │   ├── bar.py 
    │   └── __init__.py 
    ├── _static 
    └── _templates 

Dieser Baum ist das Ergebnis des Abschuss von sphinx-quickstart. In conf.py habe ich sys.path.insert(0, os.path.abspath('.')) unkommentiert und ich habe extensions = ['sphinx.ext.autodoc'].

Mein index.rst ist:

.. FooBar documentation master file, created by 
    sphinx-quickstart on Thu Aug 28 14:22:57 2014. 
    You can adapt this file completely to your liking, but it should at least 
    contain the root `toctree` directive. 

Welcome to FooBar's documentation! 
================================== 

Contents: 

.. toctree:: 
    :maxdepth: 2 

Indices and tables 
================== 

* :ref:`genindex` 
* :ref:`modindex` 
* :ref:`search` 

In allen __init__.py ‚s habe ich eine docstring und gleiche gilt für die Module foo.py und bar.py. Wenn ich make html in dem Projekt ausführe, sehe ich jedoch keinen der Docstings. Hier

Answer 1

eine Übersicht:

1. Dokument Ihres Paket mit Docstrings in den Quellen.
2. Verwenden Sie sphinx-quickstart, um ein Sphinx-Projekt zu erstellen.
3. Führen Sie sphinx-apidoc aus, um die ersten Quellen zu generieren, die für die Verwendung mit autodoc eingerichtet wurden. Mit diesem Befehl mit dem Flag -F wird auch ein vollständiges Sphinx-Projekt erstellt. Wenn sich Ihre API stark ändert, müssen Sie diesen Befehl möglicherweise mehrmals erneut ausführen.
4. Erstellen Sie die Dokumentation mit sphinx-build.

Hinweise:

• Sphinx erfordert .rst Dateien mit Richtlinien wie automodule oder autoclass, um API-Dokumentation zu generieren. Es extrahiert nichts automatisch aus den Python-Quellen ohne diese Dateien. Dies unterscheidet sich von Tools wie Epydoc oder Doxygen. Die Unterschiede sind hier ein wenig ausgearbeitet: What is the relationship between docutils and Sphinx?.

• Nachdem Sie sphinx-apidoc ausgeführt haben, müssen Sie möglicherweise sys.path in conf.py für autodoc anpassen, um Ihre Module zu finden.

• Um seltsame Fehler zu vermeiden, wie in diesen Fragen, How should I solve the conflict of OptionParser and sphinx-build in a large project?, Is OptionParser in conflict with sphinx?, stellen Sie sicher, dass der Code richtig strukturiert ist, if __name__ == "__main__": Wachen mit, wenn nötig.