Dies ist die Dokumentation für Jafar mit mkdocs

MKDocs funktioniert über eine mkdocs.yml im Wurzelverzeichnis, die die Seitenstruktur und alle Plugins festlegt. Jedes neue .md Dokument muss dort (bislang) eingetragen werden. Die Dokumente befinden sich unter /docs alle auf einer Ebene.

Als Server starten

Mit mkdocs serve im Wurzelverzeichnis des Projekts wird ein Server getartet, der die Inhalte des /docs Ordners hübscht präsentiert. Standardadresse ist http://127.0.0.1:8000/. Links stehen die "großen" Kategorien, rechts werden die durch Hashtags gebildeten Markdown-Überschriften der aktuellen Seite in der Browseransicht verlinkt.

Docstrings aus Modulen importieren

Mit dem Plugin mkdocstrings lassen sich die Docstrings aus Modulen direkt übernehmen. Dazu brauchen sie nur drei Doppelpunkte, den ganzen Pfad und ein bisschen Kontext in dieser Form:

::: src.preprocessing.data_loader
    handler: python
    show_root_heading: true
    show_source: false

Das sind wohl yaml directives.

Leider scheint der Import mit Docstrings im numpy Style nicht gut klarzukommen, hier landeten die Parameter bei mir in einem langen Fließtext oder ihre Namen verschwanden ganz. Deswegen habe ich meine Docstrings auf den Google Style geändert.

Themes

Das aktuelle Theme Material hat auch noch ein paar interessante Konfigurationsmöglichkeiten für Listen, Tabellen, LaTeX, Darkmode etc. Das readthedocs Theme ist ansonsten auch recht hübsch, aber nicht ganz optimal portiert.

— André Gasch