Sphinx für Einsteiger

Sphinx ist das Dokumentationssystem für Python. Eine Einführung findet man hier.

Die Erstellung eines Dokumentes braucht etwas Übung. Wir beschränken uns daher auf die Erstellung einer API-Dokumentation (Application Programming Interface) mit Hilfe des Befehls sphinx-apidoc.

  1. Install (Sphinx ist auf den Rechnern des Institutes für Mathematik bereits installiert)

    Installiere Sphinx z.B. mittels pip. Die PREFIX_PATH Variable sollte definiert werden, damit in das Homerverzeichnis installiert wird.

     pip install Sphinx

    or

     export PREFIX_PATH=$HOME
 pip install --install-option="--prefix=$PREFIX_PATH" Sphinx

  2. Erstelle das Grundgerüst einer Sphinx-Doku

    Variante 1: mittels sphinx-apidoc

    Die Python-Programme liegen in einem Ordner (z.B. mit dem Namen Quellordner) und die Dokumentation soll in einem Dokumentationsordner (z.B. mit dem Namen Doku) erstellt werden.

    Der Befehl sphinx-apidoc -F -H '<Name der Dokumentation>' -A '<Author>' -o <Pfad zum Ordner Doku>  <Pfad zum Quellordner> erzeugt den Dokumentationsordner und legt darin verschiedene Ordner und Files an.

    Variante 2: mittels sphinx-quickstart

    Siehe hierzu auch http://scriptsonscripts.blogspot.de/2012/09/quick-sphinx-documentation-for-python.html.

    1. Wechsle in das Projektverzeichnis und erzeuge das Verzeichnis docs/: mkdir docs; cd docs.

    2. Wechsle in das Verzeichnis docs/ und starte Sphinx mittels sphinx-quickstart. Wähle die autodoc Option mittels yes.

      Welcome to the Sphinx 1.3.1 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Enter the root path for documentation.
> Root path for the documentation [.]: 

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y

Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.
> Name prefix for templates and static dir [_]: 

The project name will occur in several places in the built documentation.
> Project name: my_project
> Author name(s): Max Mustermann

Sphinx has the notion of a "version" and a "release" for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1.  If you don't need this dual structure,
just set both to the same value.
> Project version: 0.0.1
> Project release [0.0.1]: 

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
http://sphinx-doc.org/config.html#confval-language.
> Project language [en]: 

The file name suffix for source files. Commonly, this is either ".txt"
or ".rst".  Only files with this suffix are considered documents.
> Source file suffix [.rst]: 

One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]: 

Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/n) [n]: 

Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/n) [n]: 
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: y
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: 
> coverage: checks for documentation coverage (y/n) [n]: 
> pngmath: include math, rendered as PNG images (y/n) [n]: y
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: 
> ifconfig: conditional inclusion of content based on config values (y/n) [n]: 
> viewcode: include links to the source code of documented Python objects (y/n) [n]: y

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (y/n) [y]: 
> Create Windows command file? (y/n) [y]: 

Creating file ./source/conf.py.
Creating file ./source/index.rst.
Creating file ./Makefile.
Creating file ./make.bat.

  3. Einstellungen (Pfade und mehr)

    make html, make latexpdf

    Nun kann im Dokumentationsordner mittels make-Befehl die geforderte Dokumentation erstellt werden. Sinnvoll wären make html bzw. make latexpdf.

  4. Inhalt hinzufügen -- Bearbeiten der Doku

    Die .rst Dateien im Verzeichnis source enthalten den Inhalt Ihrer Dokumentation im reStructuredText Format.
    Damit eine gut lesbare Doku entsteht, müssen die docstrings der Methoden (und ggf. weiterer Text in den *.rst Datein) also als reStructuredText (reST) formatiert werden.

    Mit der autodoc Extension, kann die Dokumentation von python Objekten(z.B. Funktionen, Methoden, Klassen oder Modulen) automatisch generiert werden. Für eine Funktion namens enumerate funktioniert das z.B. mittels

    .. autofunction:: enumerate

    Die signatur und docstrings der Funktion werden dann direkt aus dem Quellcode gelesen.

    [Auf diese Weise kann auch eine gesammte Klasse oder ganze Module dokumentiert werden.
    Beispiel für das Modul io]

    .. automodule:: io
   :members:

    Die member Option sorgt dafür, dass die docstrings aller Objekte des Moduls io verwendet werden.

    5. Die Anweisungen zur Dokumentation (z.B. von Funktionen) können 

    .. function:: enumerate(sequence[, start=0])

   Return an iterator that yields tuples of an index and an item of the
   *sequence*. (And so on.)
    sowohl in den .rst Dateien, als auch in den docstrings verwendet werden.

    Achtung
    autodoc muss die Modules importieren um die docstrings herauszufiltern. Daher muss der Pfad richtig gesetzt sein (sys.path in conf.py).
    Falls Module Seiteneffekte beim import haben, werden diese durch autodoc ausgeführt, sobald sphinx-build gestartet wird.
    Beim Schreiben von Skripten (im Gegensatz zu Bibliotheksmodulen), sollte das Hauptprogramm immer mittels if __name__ == '__main__' geschützt werden.

  5. Weiterführende Links