Die Code-Dokumentation ist ein Prozess, mit dem ein Programmierer seinen Code dokumentiert. Es ist ein bekannter Begriff unter Ingenieuren. Wenn sie dies nicht tun, führt dies zu einer schlechten Lesbarkeit des Codes und einer schwierigen Wartung für andere Teammitglieder.
Die Code-Dokumentation unterscheidet sich von der Projektdokumentation, da sie hauptsächlich darauf abzielt, wie das System funktioniert, aber diese beiden Prozesse haben etwas gemeinsam – die Anforderungen an die Verwendung eines professionellen Tools. In diesem Artikel gebe ich einen Überblick über einige gängige Werkzeuge für die Erstellung von Codedokumentation.
LaTex
LaTeX ist ein System zur Vorbereitung von Dokumenten für hochwertigen Schriftsatz. Es wird am häufigsten für mittlere bis große technische oder wissenschaftliche Dokumente verwendet, kann aber für fast jede Form der Veröffentlichung genutzt werden.
LaTeX ist keine Textverarbeitung! Stattdessen ermutigt LaTeX die Autoren, sich nicht zu sehr um das Aussehen ihrer Dokumente zu kümmern, sondern sich auf den richtigen Inhalt zu konzentrieren.
LaTeX ist ein hochwertiges Satzsystem; es enthält Funktionen, die für die Erstellung technischer und wissenschaftlicher Dokumentation entwickelt wurden. LaTeX ist der De-facto-Standard für die Kommunikation und Veröffentlichung von wissenschaftlichen Dokumenten. LaTeX ist als freie Software erhältlich.
Sie müssen für die Nutzung von LaTeX nichts bezahlen, d.h.,
Pandoc
Pandoc versteht eine Reihe nützlicher Erweiterungen der Markdown-Syntax, darunter Metadaten zum Dokument (Titel, Autor, Datum), Fußnoten, Tabellen, Definitionslisten, Hoch- und Tiefstellung, Durchstreichen, erweiterte geordnete Listen (Startnummer und Nummerierungsstil sind von Bedeutung), Listen mit laufenden Beispielen, abgegrenzte Codeblöcke mit Syntaxhervorhebung, intelligente Anführungszeichen, Gedankenstriche und Ellipsen, Markdown innerhalb von HTML-Blöcken und Inline-LaTeX. Wenn strikte Markdown-Kompatibilität gewünscht ist, können alle diese Erweiterungen ausgeschaltet werden.
Es gibt viele Möglichkeiten, Pandoc an die eigenen Bedürfnisse anzupassen, einschließlich eines Vorlagensystems und eines leistungsfähigen Systems zum Schreiben von Filtern.
Pandoc enthält eine Haskell-Bibliothek und ein eigenständiges Kommandozeilenprogramm. Die Bibliothek enthält separate Module für jedes Eingabe- und Ausgabeformat, so dass das Hinzufügen eines neuen Eingabe- oder Ausgabeformats nur das Hinzufügen eines neuen Moduls erfordert.
Pandoc ist freie Software, die unter der GPL veröffentlicht wird.
Markdown
Markdown ist ein Text-zu-HTML-Konvertierungswerkzeug für Webautoren. Markdown ermöglicht es, in einem leicht lesbaren, einfach zu schreibenden Textformat zu schreiben und es dann in strukturell gültiges XHTML (oder HTML) umzuwandeln.
Das übergeordnete Ziel für die Formatierungssyntax von Markdown ist es, sie so lesbar wie möglich zu machen. Die Idee ist, dass ein Markdown-formatiertes Dokument als reiner Text veröffentlicht werden kann, ohne dass es so aussieht, als ob es mit Tags oder Formatierungsanweisungen versehen worden wäre. Während die Markdown-Syntax von mehreren bestehenden Text-zu-HTML-Filtern beeinflusst wurde, ist die größte Inspirationsquelle für die Markdown-Syntax das Format von einfachen Text-E-Mails.
LiveEdu
LiveEdu ermöglicht es Ihnen, Ihre Code-Dokumentation zu übertragen und eine „Video-Code-Dokumentation“ zu erstellen.
Education Ecosystem ist ein dezentralisiertes Lern-Ökosystem, das Fachleuten und Studenten beibringt, wie man echte Produkte baut. Man kann unser Produkt als eine Mischung aus Pluralsight und Twitch beschreiben. Wir bauen das weltweit größte Lernökosystem für Zukunftstechnologien wie künstliche Intelligenz, Cybersicherheit, Spieleentwicklung, Datenwissenschaft, Kryptowährungen und Programmierung auf. Education Ecosystem ist videobasiert und jedes Projekt enthält Videos, eine strukturierte Projektübersicht, ein Projekt-Repository und herunterladbare Ressourcen. Benutzer können Projektressourcen aus dem Education Ecosystem Git klonen und die Anwendungen auf ihrem lokalen Rechner ausführen.
Sphinx
Sphinx ist ein Tool, das die Erstellung intelligenter und schöner Dokumentationen erleichtert. Es wurde von Georg Brandl geschrieben und ist unter der BSD-Lizenz lizenziert.
Es wurde ursprünglich für die Python-Dokumentation entwickelt und verfügt über ausgezeichnete Möglichkeiten für die Dokumentation von Softwareprojekten in einer Reihe von Sprachen. Hier sind einige Funktionen:
- Ausgabeformate: HTML (einschließlich Windows-HTML-Hilfe), LaTeX (für druckbare PDF-Versionen), ePub, Texinfo, Handbuchseiten, reiner Text.
- Umfangreiche Querverweise: semantisches Markup und automatische Links für Funktionen, Klassen, Zitate, Glossarbegriffe und ähnliche Informationen.
- Hierarchische Struktur: einfache Definition eines Dokumentbaums, mit automatischen Links zu Geschwistern, Eltern und Kindern.