Dash: Mit dem Gedächtnis einer Obstfliege produktiv programmieren
Dieser Text ist eine Übersetzung. Das Original des Programmierers Hynek Schlawack findet sich hier(öffnet im neuen Fenster) .
Seit ich Mitte der 90er Jahre mit AmigaBASIC(öffnet im neuen Fenster) anfing, ist die Programmierung deutlich vielfältiger geworden. Damals kaufte man ein sehr großes Buch über den Computer, den man gerade programmierte, und hatte 99 Prozent geschafft. Dieses Buch voller Eselsohren und Post-its lag dann neben einem, während man in seinen monochromen Editor hineinhackte, immer in Reichweite.
Heute kann schon ein Buch über das Frontend-Webframework dicker sein als das, was ein C64-Programmierer damals brauchte, um ein komplettes Spiel zu schreiben. Andererseits sind meist alle Informationen, die wir heute zum Schreiben von Code brauchen, nur einen Klick entfernt.
Niemand kann sich mehr vorstellen, für Entwicklerdokumentation zu bezahlen - sowohl Microsoft(öffnet im neuen Fenster) als auch Apple(öffnet im neuen Fenster) bieten ihre Dokumentation im Internet kostenlos an, von Open-Source-Projekten ganz zu schweigen.
In Zeiten von npm(öffnet im neuen Fenster) , PyPI(öffnet im neuen Fenster) und Github fällt es schwer zu erklären, warum es früher eine kontroverse und sorgfältig abzuwägende Entscheidung war, irgendetwas zu verlangen, das über die Funktionen des Betriebssystems hinausging. Oft wurden die Abhängigkeiten zusammen mit dem Produkt ausgeliefert.
Die neue Verfügbarkeit ist großartig und die Vielfalt ist gesund, aber sie führt zu einer Fragmentierung der Informationen, die man braucht, um produktiv zu sein.
Die Leute haben Dutzende offene Tabs mit Dokumentation für die Pakete, die sie gerade verwenden, und wechseln hektisch zwischen ihnen hin und her, um das richtige zu finden. Ich habe schon vom besten Longboarding-Spot der Welt(öffnet im neuen Fenster) aus gearbeitet, wo sich Zehntausende Menschen einen Zugangsknoten(öffnet im neuen Fenster) teilen und kann sagen: Reine Onlinesuchfunktionen sind nicht nur dann ein Problem, wenn das Internet komplett abstürzt. Gerade Onlinesuchfunktionen mit wackeligem Internet sind schlimmer als gar keine.
Für einen Polyglotten wie mich, der mit mehreren Programmiersprachen und ihren riesigen Sub-Communitys arbeitet (selbst innerhalb von Python ist Flask + SQLAlchemy + Postgres etwas ganz anderes als das Schreiben von asyncio-basierten Netzwerkservern) ist es unvorstellbar, sich alle Argumente jeder Methode zu merken, die er verwendet. Vor allem, wenn man sich wie ich schon kaum seine eigene Telefonnummer merken kann.
Deshalb hat es mein Leben verändert, als ich 2012 Dash(öffnet im neuen Fenster) entdeckte.
Dash gibt mir die Superkraft, alle relevanten APIs nur einen Tastendruck entfernt zu haben:
Ich drücke ⌥Leertaste und es öffnet sich ein schwebendes Fenster mit einer aktivierten Suchleiste. Ich tippe den ungefähren Namen der API oder des Themas ein. Ich wähle einen der Vorschläge und lande bei dem Symbol in der offiziellen Projektdokumentation. Ich drücke Escape, das schwebende Fenster verschwindet und ich kann sofort mit der Codeeingabe beginnen, da mein Editor wieder im Vordergrund ist.
Wenn ich vergessen habe, was ich gerade gelesen habe, drücke ich erneut ⌥Leertaste und das Fenster erscheint an der gleichen Stelle. Das alles geht rasend schnell - ich schaffe so eine Runde in unter 2 Sekunden. Es muss so schnell gehen, damit mein Gehirn nicht vergisst, was ich gerade gemacht habe. Inzwischen kann es das tun, ohne nachzudenken. Das ist die vergessene Glückseligkeit der nativen Anwendungen - ja, ich kenne https://devdocs.io(öffnet im neuen Fenster) !
Je weniger Energie ich darauf verwende, mich an das Argument einer Funktion oder den Importpfad einer Klasse zu erinnern, desto mehr Energie habe ich, um über das Problem nachzudenken, das ich löse. Der Aufstieg der generativen KI wie Github Copilot ändert daran nichts. Man muss zwar weniger Code schreiben, aber es wird immer wichtiger, Code - und damit APIs - zu verstehen.
Selbst wenn man einer der Glücklichen mit frühem Zugang zu Github Copilot for Docs(öffnet im neuen Fenster) ist oder fortgeschrittene ChatGPT-Modelle bezahlt: Sie sind super, um Dinge zu erklären, aber als kontinuierliche, schnelle Referenz viel zu langsam.
Dash ist eine 30-US-Dollar-Mac-Applikation (auch als Teil eines Setapp(öffnet im neuen Fenster) -Abonnements erhältlich), es gibt eine kostenlose Windows- und Linux-Version namens Zeal(öffnet im neuen Fenster) und eine 20-US-Dollar-Windows-App namens Velocity(öffnet im neuen Fenster) . Natürlich gibt es auch mindestens ein Emacs-Paket mit denselben Funktionen: helm-dash(öffnet im neuen Fenster) . Das bedeutet: Man kann dieses API-Glück auf jeder Plattform haben!
Im Folgenden werde ich nur über Dash schreiben, weil ich es benutze. Aber was ich schreibe, gilt auch für die anderen, sofern nichts anderes vermerkt ist. Gemeinsam haben alle das Format der lokalen Dokumentation. Alle verwenden Apples Documentation Set Bundles(öffnet im neuen Fenster) (docsets) - Verzeichnisse mit der HTML-Dokumentation, Metadaten in einer XML-basierten Eigenschaftsliste(öffnet im neuen Fenster) und einem Suchindex in einer SQLite(öffnet im neuen Fenster) -Datenbank.
Grenzen von Dash
Wer einen Haufen HTML-Dateien auf seiner Festplatte hat, kann diese in ein Docset konvertieren, das von Dash verwendet werden kann. Es handelt sich dabei nur um HTML-Dateien mit Metadaten. Und da es sich um HTML-Dateien auf der Festplatte handelt, funktioniert das Ganze auch offline.
Daher können Docsets Dokumentationen ersetzen, die bereits lokal auf dem Computer gespeichert sind und man kann schneller und/oder offline auf sie zugreifen. Man packt sie einfach in die erforderliche Verzeichnisstruktur, fügt einen leeren Index(öffnet im neuen Fenster) hinzu und trägt simple Metadaten ein. Bingo! Jetzt kann man sie mit einem einzigen Tastendruck herbeizaubern und mit einem weiteren wieder loswerden.
Kommen wir noch einmal auf die langweilige Geschichtsstunde vom Anfang zurück: Es gibt eine Vielzahl von Projekten, die ich auf unzähligen Plattformen verwende - jeden Tag. Und ich spreche hier nicht nur von Programmier-APIs: Ansible-Rollen, CSS-Klassen, HAProxy-Konfiguration, Eigenheiten von Postgres (und SQL!) ... das ist eine Menge! Und obwohl die Python- und Go-Kerndokumentation mit Dash ausgeliefert wird und die Godoc(öffnet im neuen Fenster) -Dokumentation direkt per URL hinzugefügt werden kann - Dash wird in der fragmentierten Welt der modernen Softwareentwicklung niemals alles bieten können, was ich brauche.
Sphinx ist die Lücke
Die größte Lücke für mich ist die Sphinx(öffnet im neuen Fenster) -basierte Dokumentation, die (nicht nur) das Python-Ökosystem dominiert. Das betrifft nicht nur API- oder narrative Dokumentation, sondern alles - mit weitreichenden Verknüpfungen. Früher war es berüchtigt dafür, dass es seinen Benutzern reStructuredText(öffnet im neuen Fenster) aufzwang, aber heutzutage verwenden immer mehr Projekte das wunderbare MyST-Paket(öffnet im neuen Fenster) , um es in Markdown zu schreiben. Allen, die Vorbehalte gegen den Look der Sphinx-Dokumentation haben, empfehle ich den Besuch der Sphinx Themes Gallery(öffnet im neuen Fenster) . Dort sieht man, wie schön solche Dokumentationen sein können. Sphinx ist in Python geschrieben, wird aber in vielen Bereichen wie im Linux-Kernel,(öffnet im neuen Fenster) in Apples Swift,(öffnet im neuen Fenster) im LLVM-Projekt Clang(öffnet im neuen Fenster) oder in sehr populären PHP-Projekten(öffnet im neuen Fenster) eingesetzt.
Und es bietet genau das, was noch fehlt: einen Index für API-Einträge, Abschnitte, Glossarbegriffe, Konfigurationsoptionen, Kommandozeilenargumente und mehr - alles beliebig in der Dokumentation verteilt, aber immer verknüpfbar. Ich finde das wunderbar, besonders wenn man einem systematischen Rahmen wie Diátaxis(öffnet im neuen Fenster) folgt.
Die Schlüsselkomponente, die dies möglich macht, ist technisch gesehen nur eine Erweiterung: intersphinx.(öffnet im neuen Fenster) Ursprünglich wurde sie für die Verknüpfung zwischen Projekten entwickelt (daher der Name) und bietet einen maschinenlesbaren Index an. Dieser wurde so beliebt, dass er nun von der MkDocs(öffnet im neuen Fenster) -Erweiterung mkdocstrings(öffnet im neuen Fenster) und pydoctor(öffnet im neuen Fenster) unterstützt wird. Intersphinx-kompatible Dokumentation ist an der Indexdatei objects.inv. zu erkennen.
Und das ist der Grund, warum ich 2012 das Doc2dash(öffnet im neuen Fenster) -Projekt gestartet habe.
Man muss das Rad nicht neu erfinden
Doc2dash ist ein Kommandozeilen-Tool. Man bekommt es auf meinem Homebrew-Tap(öffnet im neuen Fenster) und kann vorgefertigte Binärdateien(öffnet im neuen Fenster) für Linux, MacOS und Windows von der Release-Seite(öffnet im neuen Fenster) herunterladen oder von PyPI(öffnet im neuen Fenster) installieren. Dann muss man ihm nur noch den Verweis auf ein Verzeichnis mit intersphinx-kompatibler Dokumentation geben und das Tool stellt ein Docset zur Verfügung.
Man beachte, dass der Name Doc2dash und nicht Sphinx2dash lautet. Es ist eigentlich zum Schreiben qualitativ hochwertiger Converter gedacht, von denen Sphinx und Pydoctor die Ersten waren. Leider hat das so nicht funktioniert, weil verständlicherweise jede Community ihre eigene Sprache und ihre eigenen Werkzeuge verwenden wollte. Da diese Tools meist ziemlich einzigartig sind, würde ich gern mit anderen daran arbeiten, Unterstützung für andere Dokumentationsformate hinzuzufügen. Man muss das Rad nicht neu erfinden, das Framework ist bereits vorhanden! Es ist nur ein Haufen Code-Zeilen(öffnet im neuen Fenster) , niemand muss mit mir oder dem Rest der Welt seinen Parser teilen.
Obwohl es Dash und Doc2dash schon seit mehr als zehn Jahren gibt, sehe ich immer noch Freunde, die eine Milliause Tabs mit API-Dokumentation geöffnet haben, und das bricht mir das Herz. Ich zeige Leuten immer wieder Dash im Einsatz, sie sagen dann, dass sie es cool finden, und setzen es auf ihre Irgendwann-erledigen-Liste. Wenn man sie nicht noch mal anstößt, wird dieses Irgendwann nie eintreffen.
Dieser Anstoß soll die folgende Schritt-für-Schritt-Anleitung sein (hier endet der Obstfliegen-Teil des Artikels). "Irgendwann" ist heute!
Doc2Dash: eine Anleitung
Diese Anleitung zeigt, wie eine intersphinx-kompatible Dokumentation in ein Docset konvertiert und an die von Benutzern erstellte Docset-Registry(öffnet im neuen Fenster) von Dash übermittelt werden kann, so dass andere keine Arbeit doppelt machen müssen. Ich gehe davon aus, dass bereits ein API-Brower installiert wird. Welcher, ist egal, ich verwende Dash. Für das optionale Einreichen des Docsets am Ende ist außerdem ein grundlegendes Verständnis von Github und seinem Pull-Request-Workflow(öffnet im neuen Fenster) Voraussetzung.
Ich nehme diese Anleitung zum Anlass, endlich Docsets meiner eigenen Projekte zu veröffentlichen, angefangen mit structlog(öffnet im neuen Fenster) . Jeder wähle sich nun ein intersphinx-kompatibles Projekt aus, das noch nicht von Dash unterstützt wird und dessen Dokumentations-Tab er oder sie besonders häufig besucht.
Los geht's!
Doc2dash installieren
Wer bereits Homebrew(öffnet im neuen Fenster) nutzt, kann einfach meinen Tap(öffnet im neuen Fenster) benutzen:
$ brew install hynek/tap/doc2dash
Es stehen Bottles(öffnet im neuen Fenster) für Linux x86-64 und MacOS sowohl auf x86-64 als auch auf Apple-Silizium bereit, so dass die Installation sehr schnell gehen sollte. Für diejenigen, die sich nicht mit der Paketierung von Python auskennen, ist der nächstbeste Weg, die vorgefertigten Binärdateien von der Veröffentlichungs-Seite(öffnet im neuen Fenster) zu nutzen. Derzeit werden Binärdateien für Linux, Windows und MacOS angeboten - alle auf x86-64. Mehr Möglichkeiten sollen folgen, wenn der Bedarf besteht.
Der letzte mögliche Weg ist es, Doc2dash von PyPI(öffnet im neuen Fenster) zu beziehen. Ich empfehle dabei dringend die Verwendung von pipx(öffnet im neuen Fenster) , und der einfachste Weg, Doc2dash damit auszuführen, ist:
$ pipx run doc2dash --help
Pro-Tipp für Fortgeschrittene, die wissen, was PyPy ist und wie man es benutzt und planen, riesige Dokumentationsbäume zu konvertieren: Doc2dash ist unter PyPy(öffnet im neuen Fenster) mehr als doppelt so schnell wie unter CPython.(öffnet im neuen Fenster) Wer von alledem nichts versteht, ignoriere einfach diesen Absatz und nehme sich ein Heißgetränk.
Die Dokumentation aufbauen
Was jetzt kommt, ist das größte Problem, für das es die meisten Funktionswünsche zu Doc2dash gibt: Man benötigt eine Dokumentation in einer vollständigen, gut aufgebauten Form. Normalerweise muss man dafür das Repository herunterladen und herausfinden, wie man die Dokumentation erstellt, bevor man überhaupt Doc2dash installiert. Die meisten Dokumentationsseiten bieten nämlich nicht an, das ganze Ding herunterzuladen.
Mein heuristischer Ansatz ist es, zunächst nach einer tox.ini oder noxfile.py zu suchen und zu sehen, ob sie die Dokumentation erstellt. Ist das nicht der Fall, suche ich nach einer . readthedocs.yaml(öffnet im neuen Fenster) . Hilft das auch nicht weiter, suche ich Dateien mit Namen wie docs-requirements.txt oder optionalen Installationszielen wie docs. Die letzte Möglichkeit es es, die YAML-Seiten durchzugehen und die CI-Konfigurationen zu überprüfen.
Wenn man es geschafft hat, alle Abhängigkeiten zu installieren, ist es normalerweise nur noch eine Frage von make html im Dokumentationsverzeichnis. Nachdem wir das herausgefunden haben, brauchen wir ein Verzeichnis namens _build/html für Sphinx oder site für MkDocs.
Beachtet werden sollte, dass es bei MKDOcs keine objects.inv -Datei gibt und daher keine API-Daten genutzt werden können, wenn das Projekt nicht die mkdocstrings-Erweiterung verwendet - was derzeit leider für praktisch alle gängigen Projekte gilt. In Zukunft werden hoffentlich mehr MKDocs-basierte Projekte Unterstützung für mkdocstrings hinzufügen. Wie Sphinx ist es sprachunabhängig.
Konvertierung
Nach dem schwierigsten Schritt folgt der einfachste: die Konvertierung der soeben erstellten Dokumentation in ein Docset. Man muss nur Doc2dash auf das Verzeichnis mit der HTML-Dokumentation richten und warten:
$ doc2dash _build/html
Das ist alles!
Doc2dash weiß, wie man den Namen aus dem intersphinx-Index extrahiert, und verwendet ihn standardmäßig (er kann mit --name überschrieben werden). Wird dieses Docset zu einem API-Browser hinzugefügt, sollte alles funktionieren.
Wird --add-to-dash oder -a übergeben, wird das Docset automatisch zu Dash hinzugefügt, wenn es fertig ist. Wird --add-to-global oder -A übergeben, wird das fertige Docset in ein globales Verzeichnis (~/Library/Application Support/doc2dash/DocSets) verschoben und von dort aus hinzugefügt. Ich lasse Doc2dash selten ohne -A laufen, wenn ich selbst Docsets erstelle.
Die Dokumentation verbessern
Die Dokumentation von Dash enthält eine Reihe von Empfehlungen(öffnet im neuen Fenster) , um die im vorherigen Schritt erstellte Dokumentation zu verbessern. Es ist wichtig zu beachten, dass die nächsten fünf Schritte rein optional sind und ich sie meistens aus Faulheit überspringe. Aber in diesem Fall möchte ich das Docset an die von den Benutzern erstellte Registry von Dash übermitteln, also bis zum Ende gehen.
Einstellen der Hauptseite
Mit Dash kann man immer alle installierten Dokumentsätze durchsuchen, aber manchmal möchte man den Umfang der Suche einschränken. Wenn ich zum Beispiel p3: (der Doppelpunkt ist wichtig) eingebe, schaltet Dash auf die Suche nach Python 3 um. Bevor wir mit der Eingabe beginnen, bietet es ein Menü unterhalb des Suchfeldes an, dessen erster Punkt Hauptseite ist.
Bei der Konvertierung von structlog-Dokumenten ist diese Hauptseite der Index. Er kann nützlich sein, ist es für mich aber meistens nicht. Wenn ich auf der Hauptseite angekommen bin, möchte ich in der narrativen Dokumentation blättern.
Die Doc2dash-Option, um die Hauptseite zu setzen, ist --index-page oder -I und nimmt den Dateinamen der Seite, die wir verwenden wollen, relativ zum Stammverzeichnis der Dokumentation.
Verwirrenderweise ist der Dateiname des Index genindex.html und der Dateiname der Hauptseite ist HTML-typisch index.html . Deshalb fügen wir --index-page index.html in die Befehlszeile ein.
Ein Icon hinzufügen
Dokumentationsgruppen können mit Symbolen versehen werden, die in Dash neben den Namen und Symbolen der Dokumentationsgruppen angezeigt werden. Das ist nicht nur hübsch, sondern auch hilfreich, um Docsets schneller zu erkennen, oder um zu sehen, woher ein Symbol kommt, wenn man in mehreren Docsets sucht. Structlog hat ein niedliches Biberlogo, also benutzen wir ImageMagick(öffnet im neuen Fenster) , um das Logo auf 16x16 Pixel zu verkleinern:
$ magick \
docs/_static/structlog_logo_transparent.png \
-resize 16x16 \
docs/_static/docset-icon.pngJetzt können wir es mit der Option --icon docset-icon.png zum Dokumentsatz hinzufügen.
Unterstützung der Onlineweiterleitung
Offline-Dokumente sind großartig, aber manchmal kann es nützlich sein, zur Onlineversion der Dokumentationsseite zu wechseln, die man gerade liest, zum Beispiel, um eine neuere oder ältere Version zu lesen.
Dash hat dafür den Menüpunkt Open Online Page ⇧⌘B , aber es muss die Basis-URL der Dokumentation kennen. Dies kann mit --online-redirect-url oder -u eingestellt werden. Für Python-Pakete kann bei Read the Docs(öffnet im neuen Fenster) zwischen stable (letzter VCS-Tag) und latest (aktueller Hauptzweig) gewählt werden. Für mich scheint latest sinnvoller, wenn man den Komfort der Offline-Dokumentation verlässt, daher füge ich es hinzu:
--online-redirect-url https://www.structlog.org/en/latest/
Alles zusammenfügen
Geschafft! Führen wir die gesamte Befehlszeile aus, sieht sie in Dash so aus:
$ doc2dash \
--index-page index.html \
--icon docs/_static/docset-icon.png \
--online-redirect-url https://www.structlog.org/en/latest/ \
docs/_build/html
Converting intersphinx docs from '/Users/hynek/FOSS/structlog/docs/_build/html' to 'structlog.docset'.
Parsing documentation...
Added 238 index entries.
Patching for TOCs...________________________ 100% 0:00:00Herrlich:
Unter Beachtung des Icons in der Suchleiste bringt mich die Tastenkombination ⇧⌘B auf jeder Seite mit einem Anker an dieselbe Stelle in der aktuellen Version der Onlinedokumentation.
Automatisierung
Da ich für jedes neue Release eine neue Version der Docsets erstellen möchte, muss die Erstellung automatisiert werden. Structlog nutzt bereits Github Actions als CI, also ist es sinnvoll, es auch für die Erstellung der Docsets zu nutzen.
Für lokale Tests mache ich mir zum Vorteil, dass Doc2dash ein Python-Projekt ist, und nutze eine Tox-(öffnet im neuen Fenster) Umgebung, die mit den Abhängigkeiten arbeitet, die ich beim Testen der Dokumentation selbst verwende.
Tox ist eine Kombination aus make und einem virtuellen Umgebungsmanager, der auf dem ini-Dateiformat basiert. Sein ursprünglicher Zweck war es, Python-Software über mehrere Python-Versionen hinweg zu testen, aber inzwischen kann er noch viel mehr.
Die großen Vorteile gegenüber einem Makefile sind, dass es portabler ist und eingebaute Unterstützung für Python-Pakete hat (was für die Erstellung der Dokumentation sowieso notwendig ist).
Die Umgebung installiert structlog[docs] , also das Paket mit den optionalen docs-Abhängigkeiten plus Doc2dash. Dann führt sie die Befehle der Reihe nach aus:
[testenv:docset] extras = docs deps = doc2dash allowlist_externals = rm cp tar commands = rm -rf structlog.docset docs/_build sphinx-build -n -T -W -b html -d {envtmpdir}/doctrees docs docs/_build/html doc2dash --index-page index.html --icon docs/_static/docset-icon.png --online-redirect-url https://www.structlog.org/en/latest/ docs/_build/html cp docs/_static/docset-icon@2x.png structlog.docset/icon@2x.png tar --exclude='.DS_Store' -cvzf structlog.tgz structlog.docset
Jetzt kann ich ein Docset erstellen, indem ich einfach tox -e docset aufrufe. Bis Doc2dash hochauflösende Icons unterstützt(öffnet im neuen Fenster) , kopiert es auch eine 32 x 32 Pixel große Version des Logos direkt in das Docset.
Das geht einfach in CI, verursacht aber tonnenweise Boilerplates, daher verlinke ich einfach auf den Workflow(öffnet im neuen Fenster) . Wichtig ist die Upload-Artefakt-Aktion am Ende, mit der ich die erstellten Docsets aus den Laufzusammenfassungen herunterladen kann.
An diesem Punkt haben wir ein großartiges Dokumentset, das automatisch erstellt wurde. Teilen wir es mit der Welt!
Das Docset teilen
Im letzten Schritt übermitteln wir unser Docset an das Dash-Repository, so dass andere es bequem über die Dash-Benutzeroberfläche herunterladen können. Praktischerweise verwendet Dash für den gesamten Prozess(öffnet im neuen Fenster) ein Konzept, das wahrscheinlich jedem Open-Source-Kenner bekannt ist: Github Pull Requests.
Als Erstes überprüfen wir die Docset Contribution Checklist(öffnet im neuen Fenster) . Glücklicherweise haben wir - oder in manchen Fällen: Doc2dash - uns bereits um alles gekümmert!
Machen wir also gleich weiter und forken das https://github.com/Kapeli/Dash-User-Contributions(öffnet im neuen Fenster) Repo und klonen es auf den Computer.
Zuerst kopieren wir das Sample_Docset-Verzeichnis in Docsets und benennen es dabei um. Die Befehlszeile ist also für mich:
$ cp -a Sample_Docset docsets/structlog
Gehen wir ins Verzeichnis mit cd docsets/structlog und machen von dort aus weiter. Der wichtigste Schritt ist das Hinzufügen des Docsets selbst, allerdings als gzipped-tar -Datei. Der Contribution Guide gibt uns sogar die Vorlage für die Erstellung. In meinem Fall lautet die Befehlszeile:
$ tar --exclude='.DS_Store' -cvzf structlog.tgz structlog.docset
Das Taring habe ich bereits in meiner Tox-Datei vorgenommen habe, so dass ich es nur noch kopieren muss:
$ cp ~/FOSS/structlog/structlog.tgz .
Außerdem sollen die Symbole zusätzlich zu denen im Dokumentsatz angezeigt werden, also kopiere ich sie aus dem Dokumentsatz:
$ cp ~/FOSS/structlog/structlog.docset/icon* .
Als Nächstes müssen die Metadaten in die Datei docset.html eingetragen werden, was in meinem Fall ganz einfach ist:
{
"name": "structlog",
"version": "22.1.0",
"archive": "structlog.tgz",
"author": {
"name": "Hynek Schlawack",
"link": "https://github.com/hynek"
},
"aliases": []
}
Als Letztes werden wir aufgefordert zu dokumentieren, wer wir sind und wie wir das Docset gebaut haben. Nachdem ich mir andere Beispiele(öffnet im neuen Fenster) angesehen habe, entscheide ich mich für die folgende Variante:
# structlog
<https://www.structlog.org/>
Maintained by [Hynek Schlawack](https://github.com/hynek/).
## Building the Docset
### Requirements
- Python 3.10
- [*tox*](https://tox.wiki/)
### Building
1. Clone the [*structlog* repository](https://github.com/hynek/structlog).
2. Check out the tag you want to build.
3. `tox -e docset` will build the documentation and convert it into `structlog.docset` in one step.Der Tox-Trick zahlt sich aus - ich muss niemandem mehr erklären, wie man Python verpackt!
Nicht vergessen, alles aus der Beispieldokumentation zu löschen, was wir nicht brauchen:
$ rm -r versions Sample_Docset.tgz
Fertig! Kontrollieren wir in unseren Änderungen:
$ git checkout -b structlog
$ git add docsets/structlog
$ git commit -m "Add structlog docset"
[structlog 33478f9] Add structlog docset
5 files changed, 30 insertions(+)
create mode 100644 docsets/structlog/README.md
create mode 100644 docsets/structlog/docset.json
create mode 100644 docsets/structlog/icon.png
create mode 100644 docsets/structlog/icon@2x.png
create mode 100644 docsets/structlog/structlog.tgz
$ git push -u
Das ist gut aus - Zeit für einen Pull Request!(öffnet im neuen Fenster)
Ein paar Stunden später:
Ein großer Erfolg: Jeder kann jetzt das structlog Documentation Set herunterladen, das unsere kleine Anleitung abschließt!
Ich hoffe, ich habe das Interesse für API-Dokumentationsbrowser geweckt und die Erstellung eigener Dokumentationspakete entmystifiziert. Damit möchte ich Programmierern helfen, die - wie ich - überwältigt von all den Paketen sind, die sie bei der Arbeit im Auge behalten müssen. Und ich hoffe, dass jemand inspiriert wird, gemeinsam mit mir weitere Formate zu Doc2Dash hinzuzufügen, damit noch mehr Programmierer in den Genuss der einfachen API-Dokumentation kommen.
Disclaimer: Mir wurde vorgeworfen, der Artikel sei Werbung. Daher die Klarstellung: Ich habe keine Geschäftsbeziehung mit dem Dash-Autor und er wusste nichts davon, dass ich diesen Artikel schreibe, bis ich ihm eine späte Version zum Faktencheck gezeigt habe. Manchmal mögen Menschen eben ein Produkt, das Geld kostet, und es sollte möglich sein, auch darüber zu schreiben, wie es das eigene Arbeitsleben umgekrempelt hat. Ganz besonders, wenn es von einem Indie-Developer kommt! Update:
Der Artikel wurde auf seine Aktualität überprüft.