Übersicht und Benutzung von Sphinx Dokumentation Übersicht und Benutzung von Sphinx
Problem ohne Dokumentation Große Projekte Entwickler auf der ganzen Welt Unübersichtlicher Code Schlechte Wartbarkeit
Dokumentation mit DocStrings String-Literal als erste Anweisung einer Funktion, Klasse oder eines Moduls DocString kann über __doc__ Attribut oder help() abgerufen werden
Dokumentation mit DocStrings Syntax (Format: reStructuredText): Dreifache Anführungszeichen am Anfang und am Ende Zeilenabsatz vor und nach der Beschreibung Parameter: :param arg_1: Some argument :type param1: str :param param1 str: Some argument Return: - :return: Some return value :rtype: str
Beispiel def example_method(arg_1, arg_2): """ This is an example method :param arg_1 str: some string argument :param arg_2: another argument :return: some integer return value :rtype: int
Dokumentation mit Sphinx Tool um Dokumentationen per Hand oder automatisch aus DocStrings zu erstellen Über sphinx-quickstart können schnell neue Projekte erstellt werden Plattformen wie z.B. HTML und Latex können ausgewählt werden
Quickstart - Beispielprojekt Manuelles einfügen von Dokumentation Über index.rst werden die Dokumentationsdateien im toctree (Table of contents tree) angegeben Hierarchische Struktur In den Dokumentationsdateien können Klassen, Methoden und Funktionen durch reStructuredText dokumentiert werden: .. module:: name .. class:: name (params) .. method:: name (params) .. function:: name (params) Automatische Generierung aus DocStrings Mithilfe von den Direktiven .. automodule:: und .. autoclass:: können automatisch Dokumentationen aus bestehenden Projekten mit DocStrings hinzugefügt werden
Fragen?
Quellen https://www.python.org/dev/peps/pep-0257/ https://cito.github.io/byte_of_python/read/docstrings.html http://daouzli.com/blog/docstring.html http://www.sphinx-doc.org/en/master/usage/quickstart.html http://www.sphinx- doc.org/en/master/usage/restructuredtext/directives.html#toctree- directive http://www.sphinx- doc.org/en/master/usage/extensions/autodoc.html#module- sphinx.ext.autodoc