Dokumentation von Programmier Projekten zu erstellen ist für die meisten Programmierer weder angenehm noch einfach. Da liegt es recht nahe, Tools zu entwickeln die einem die Arbeit auch bei der Dokumentation erleichtern. Ich selber verwende in Python dafür sphinx.
Mit sphinx kann man automatisiert eine Webseite mit der Dokumentation der Funktionen einen Programmes erstellen. Voraussetzung dafür ist, dass man die notwendigen Funktionen mit einem guten docstring versehen hat.
Beispiel Python Code
Um euch das ganze einmal zu zeigen habe ich eine kleines Python Script mit Funktionen und docstring vorbereitet:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 | def get_hello_word(): """ returns the string 'Hello World' Parameters ---------- Returns ------- string 'Hello World' """ return 'Hello World' def sum_of_2_variables(a,b): """ Sum of two variables Parameters ---------- a : int 1st number b : int 2nd number Returns ------- int sum of variable a and b """ return a + b |
Die Ordnerstruktur hat einen Ordner wo die Projektdateien drin liegen und einen separaten Ordner für die Dokumentation. Das sieht dann wie folgt aus:
Installation von sphinx und Setup mit quickstart
Um nun automatisiert die Dokumentation zu erstelle, muss man als erstes mittels pip die notwendigen Pakete installieren.
1 | pip install -U sphinx |
Nach der Installation von sphinx kann eine Grundkonfiguration mit dem Befehl sphinx-quickstart durchgeführt werden. Dabei werden alle benötigten Konfigurationsdateien anhand einiger weniger Eingaben automatisch angelegt. Der Befehl wird direkt auf dem Terminal ausgeführt. Wichtig hierbei ist, dass man sich im Verzeichnis docs befindet.
Bei mir sah das ganze wie folgt aus:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 | sphinx-quickstart Welcome to the Sphinx 4.2.0 quickstart utility. Please enter values for the following settings (just press Enter to accept a default value, if one is given in brackets). Selected root path: . 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]: n The project name will occur in several places in the built documentation. > Project name: Modius-Techblog Doc Test > Author name(s): Christian Piazzi > Project release []: 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 https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language. > Project language [en]: Creating file C:\Users\Modius\PycharmProjects\Sandbox\docs\conf.py. Creating file C:\Users\Modius\PycharmProjects\Sandbox\docs\index.rst. Creating file C:\Users\Modius\PycharmProjects\Sandbox\docs\Makefile. Creating file C:\Users\Modius\PycharmProjects\Sandbox\docs\make.bat. Finished: An initial directory structure has been created. You should now populate your master file C:\Users\Modius\PycharmProjects\Sandbox\docs\index.rst and create other documentation source files. Use the Makefile to build the docs, like so: make builder where "builder" is one of the supported builders, e.g. html, latex or linkcheck. |
Nun solltet ihr einige Dateien im docs Ordner haben.
Manuelle Anpassung der Konfigurationsdateien
Ein paar kleine Anpassungen nehme ich nach dem automatischen erstellen der Konfiguration dann immer in der conf.py vor, damit die Dokumentation direkt aus den docstrings generiert werden kann. Zusätzlich muss in der dritten Zeile im Pfad der . durch einen .. ersetzt werden.
In Zeile 13 – 15 findet man ein paar Imports. Diese kommentiere ich ein.
1 2 3 4 5 6 7 8 9 10 11 | #Vorher # import os # import sys # sys.path.insert(0, os.path.abspath('.')) #Nachher import os import sys sys.path.insert(0, os.path.abspath('..')) |
Anschließend suchen wir in der Datei nach dem Schlüsselwort extensions. Hier ist eine Liste in der wir noch die Napoleon Erweiterung hinzufügen müssen.
1 | extensions = ['sphinx.ext.autodoc', 'sphinx.ext.coverage', 'sphinx.ext.napoleon'] |
Die conf.py kann nun gespeichert und geschlossen werden.
Als nächstes wird die index.rst geöffnet. Das Kommentar am Anfang der Datei kann einfach gelöscht werden. Vor den Eintrag mit dem toctree ergänzen wir nun noch einen automodule Eintrag. Das Ergebnis sieht dann wie folgt aus:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | Welcome to Modius-Techblog Doc Test's documentation! ==================================================== .. automodule:: src.main :members: .. toctree:: :maxdepth: 2 :caption: Contents: Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` |
Erstellen der html Dateien
Nun können wir die Dokumentation im html Format erzeugen. Dazu müssen wir wieder auf dem Terminal arbeiten. Hier ist es wichtig, dass man sich wieder im Ordner docs befindet.
Auf dem Termin führt man dann den Befehl make html aus. Das ganze sollte dann wie folgt aussehen:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | make html Running Sphinx v4.2.0 making output directory... done building [mo]: targets for 0 po files that are out of date building [html]: targets for 1 source files that are out of date updating environment: [new config] 1 added, 0 changed, 0 removed reading sources... [100%] index looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] index generating indices... genindex py-modindex done writing additional pages... search done copying static files... done copying extra files... done dumping search index in English (code: en)... done dumping object inventory... done build succeeded. The HTML pages are in _build\html. |
Die letzte Ausgabe weist bereits darauf hin, wo die html Dateien gefunden werden können.
Wenn man nun in den Ordner geht und einen Doppelklick auf die index.html macht, sollte diese automatisch im Browser aufgehen. Das ganze sieht dann wie folgt aus:
Wie man sieht, ist es noch nicht optimal, aber die beiden erstellten Funktionen werden mit den Informationen aus dem docstring hier aufgeführt.
Optional – Änderung des Themes
Ich benutze ganz gerne das Read the Docs Theme. Die meisten von euch werden das von OpenSource Dokumentationsseiten kennen.
Ein zusätzliches sphinx Theme kann ganz einfach mit pip installiert werden:
1 | pip install sphinx-rtd-theme |
In der conf.py findet ihr einen Eintrag html_theme. Hier steht bereits ein Theme drin. Dieses wird einfach ersetzt.
1 2 3 4 5 6 | #vorher html_theme = 'alabaster' #nachher html_theme = 'sphinx_rtd_theme' |
Nach dem speichern der Datei wird wieder make html ausgeführt. Wenn man das ganze nun im Browser aufruft, sieht es wie folgt aus:
Ich persönlich finde es so direkt ansprechender. Aber das ist ja bekanntlich Geschmackssache =)
Super Beitrag. Einfach, nachvollziehbar, stimmig. Hatte mich bereits mit einigen Tutorials erfolglos beschäftigt. Mit diesen wenigen Zeilen hat es nun gleich geklappt.
Danke
Sepp