Dokumentieren¶
Damit euer Software-Paket sinnvoll genutzt werden kann, sind Dokumentationen ierforderlich, die Beschreiben, wie eure Software installiert, betrieben, genutzt und verbessert werden kann:
Diejenigen, die euer Paket nutzen wollen, benötigen Informationen,
welche Probleme eure Software löst und was die Hauptfunktionen und Limitationen der Software sind (
README)wie das Software beispielhaft verwendet werden kann
welche Veränderungen in aktuelleren Software-Versionen gekommen sind (
CHANGELOG)
Diejenigen, die die Software betreiben wollen, benötigen eine Installationsanleitung für eure Software und die erforderlichen Abhängigkeiten
Diejenigen, die die Software verbessern wollen, benötigen Informationen
wie sie mit Fehlerbehebungen zur Verbesserung des Produkts beitragen können (
CONTRIBUTING)wie sie mit anderen kommunizieren (
CODE_OF_CONDUCT) können
Alle gemeinsam benötigen Informationen, wie das Produkt lizenziert ist
(LICENSE-Datei oder LICENSES-Ordner) und wie sie bei Bedarf Hilfe
erhalten können.
Siehe auch
Badges¶
Einige dieser Informationen und mehr können als Badges abgerufen werden. Sie sind hilfreich, um einen schnellen Überblick über ein Produkt zu erhalten. Für das cookiecutter-namespace-template sind dies z.B.:
Ihr könnt auch eigene Badges erstellen, z.B.:
Siehe auch
Sphinx¶
Für umfangreiche Dokumentationen könnt ihr z.B. Sphinx verwenden, ein Dokumentationswerkzeug, das reStructuredText in HTML oder PDF, EPub und man pages umwandelt. Auch die Python Basics werden mit Sphinx erstellt. Um einen ersten Eindruck von Sphinx zu bekommen, könnt ihr euch den Quellcode dieser Seite unter dem Link Page source ansehen.
Ursprünglich wurde Sphinx für die Dokumentation von Python entwickelt und wird heute in fast allen Python-Projekten verwendet, darunter NumPy and SciPy, Matplotlib, Pandas und SQLAlchemy.
Die Sphinx autodoc-Funktion, die zur Erstellung von Dokumentation aus Python-Docstrings verwendet werden kann, könnte ebenfalls zur Verbreitung von Sphinx unter Python-Entwicklern beitragen. Insgesamt ermöglicht es Sphinx Entwicklungsteams, eine vollständige Dokumentation an Ort und Stelle zu erstellen. Oft wird die Dokumentation auch im gleichen Git-Repository gespeichert, so dass die Erstellung der neuesten Software-Dokumentation einfach bleibt.
Sphinx wird auch in Projekten außerhalb der Python-Gemeinschaft eingesetzt, z.B. für die Dokumentation des Linux-Kernels: Kernel documentation update.
Read the Docs wurde entwickelt, um die Dokumentation weiter zu vereinfachen. Read the Docs erleichtert das Erstellen und Veröffentlichen von Dokumentationen nach jedem Commit.
Für die Projektdokumentation kann die Visualisierung von Git Feature Branches und Tags mit git-big-picture hilfreich sein.
Bemerkung
Wenn der Inhalt von long_description in setup() in reStructured Text
geschrieben ist, wird er als gut formatiertes HTML im Python Package
Index (PyPI) angezeigt.