Übersicht und Benutzung von Sphinx

Präsentation zum Thema: "Übersicht und Benutzung von Sphinx"—  Präsentation transkript:

1 Übersicht und Benutzung von Sphinx
Dokumentation Übersicht und Benutzung von Sphinx

2 Problem ohne Dokumentation
Große Projekte Entwickler auf der ganzen Welt Unübersichtlicher Code Schlechte Wartbarkeit

3 Dokumentation mit DocStrings
String-Literal als erste Anweisung einer Funktion, Klasse oder eines Moduls DocString kann über __doc__ Attribut oder help() abgerufen werden

4 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

5 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

6 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

7 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

8 Fragen?

9 Quellen https://www.python.org/dev/peps/pep-0257/
doc.org/en/master/usage/restructuredtext/directives.html#toctree- directive doc.org/en/master/usage/extensions/autodoc.html#module- sphinx.ext.autodoc