Programmieren eines Dokutools mit Doxygen und lbuild Anbindung und Automatisierung von Doku-Qualitätkontrollen.

Zusammenfassung

Sowohl xpcc als auch modm [1] sind relativ gut im Code mittels Doxygen dokumentiert. Für xpcc haben wir somit einfach den generierten Doxygenoutput online gestellt [2]. Doxygen eignet sich allerdings nicht besonders gut für Konzeptdokumentation und Beispielcode.

Mit lbuild [3] ist modm in mehrere Module aufgeteilt, die jeweils nur eine überschaubare Anzahl an Klassen verwalten. Diese Module können separat in Markdown dokumentiert werden und erlauben detailierte Konzeptdokumentation [4]. Die Doxygendokumentation des Codes kann als XML ausgegeben und per Python3 eingelesen werden [5], momentan, werden allerdings nur die wichtigsten Objektnamen angezeigt [6].

Es soll ein Konzept erarbeitet werden, wie am Besten die Doxygendokumentation in die Moduldokumentation eingebunden werden kann, sodass es einfach ist komplexe Dokumentation zu schreiben und mit der Implementation zu verlinken. Desweiteren sollen Beispiele in der Moduldokumentation kompilierbar sein, und wenn möglich weitere Überprüfungen (zB. valide Objektnamen im Fließtext) als Teil des CIs implementiert werden. Damit soll die Dokumentation synchron zur Implementierung gehalten werden. Abschließend soll diese Dokumentation visuell ansprechendend, durchsuchbar und gut navigierbar unter docs.modm.io automatisch deployed werden.

In Zukunft soll dieses Tool auch für librobots und evtl. andere RCA Projekte verwendet werden. Als Vorbild für Design und Vollständigkeit gilt die Qt5 Dokumentation [7].

Es ist explizit nicht erforderlich, Dokumentation für modm zu schreiben! Es geht hier um die automatische Erstellung und Pflege der Dokumentation, nicht unbedingt den Inhalt.

Tätigkeitsfelder und Technologien

  • Doxygen XML Auswertung für Assembly, C, C++
  • Python3 und Jinja2 für Datenumwandlung und Dokumentationsgeneration
  • Editieren Technischer Dokumentation
  • Automatische Compilierung von Beispielcode
  • Automatisches Deployment der Dokumentation
  • Webdevelopment und -design, evtl. mit vorhandener Doku-Engine

Referenzen und Links

  • [1] https://modm.io
  • [3] https://xpcc.io/api
  • [2] https://github.com/dergraaf/library-builder
  • [4] https://modm.io/reference/module/modm-platform-core
  • [5] https://github.com/modm-io/modm/blob/feature/docs/tools/doc_generator/module.lb
  • [6] https://modm.io/reference/module/modm-architecture
  • [7] https://doc.qt.io