Hi, >>> ich wollte nur kurz anmerken, dass ich mit dem neuen Layout von >>> BitBucket ziemlich glücklich bin. Das ist wirklich ein schönes Tool >>> für Kollaboration. >> >> Und ich bin ganz begeistert vom Code-Browsing bei den diversen Social >> Coding Plattformen, wo in jedem Ordner standardmäßig eine README >> angezeigt wird. Das hilft ungemein dabei, die Ordnerstruktur von >> Quellcode zu verstehen. Ich warte nur darauf, bis die Annotationen im >> Quellcode auch hübsch geparst werden und man darin wie in einem Buch >> lesen kann. >> > > Denkst du, wir sollten neben der README im Stammverzeichnis auch noch in > den entsprechenden Unterverzeichnissen welche hinterlegen? Das hört sich > interessant und nützlich an, ist aber ein weiterer Dokumentationsteil der > entsprechend gepflegt werden muss. Vielleicht sollten wir vorher die > gewünschte Struktur auch nochmal ausdiskutieren. Da gab es ja auch > verschiedene Vorstellungen.
Nicht unbedingt in jedem Unterverzeichnis. Aber an einigen Stellen kann das sehr nützlich sein. Diese READMEs richten sich dann eher an Leute, die den Quellcode, bzw. die interne Projektstruktur leichter verstehen wollen. So etwas sollte sich nicht unbedingt ständig ändern. Natürlich ist das auch erst dann sinnvoll, wenn es genauere Vorstellungen über die Struktur gibt. >>> Wir sollten vielleicht auch langsam anfangen Design-Konzepte usw. >>> auch dort im Wiki zu pflegen. Das Wiki ist bei BitBucket ein eigenes >>> Git Repository, in welchem Markdown-Texte (oder alternatives >>> Markup?) gepflegt werden. >> >> Bei reStructuredText gibt es bei Bitbucket auf jeden Fall Probleme mit >> dem Einbinden von Bildern. Keine Ahnung, wie das bei Mardown >> aussieht. Bilder-Upload über das Web-Interface ist ebenfalls >> problematisch, weil die Bilder nicht im Repository landen. Verglichen >> zum Schreiben von Offline-Dokumentation macht die Arbeit in einem Wiki >> zwar wesentlich mehr "Spaß" und fühlt sich "schneller" an. >> >> Aber: In welchem Maße bindet man sich damit an Bitbucket? Sollte man >> nicht in der Lage sein, die Doku auch separat auszuliefern? >> > > Wie gesagt ist das Wiki bei BitBucket auch nur ein weiteres Git Repo, das > man ebenso lokal halten und ändern kann. Das Format sollte ziemlich > einfach strukturiert sein. Ich denke das kann man dann auch getrennt von > BitBucket hosten/parsen/setzen, wenn es sein muss. > > Wie das mit Bildern und anderen Dateien aussieht habe ich bisher nicht > ausprobiert. Das könnte problematischer sein. wenn die nicht mit im Repo > landen. Man kann online keine Ordnerstrukturen anlegen und keine Bilder im Repository hinzufügen. Daher taugt es nur als Anzeige und so lange man keine neuen Dokumente unterhalb des Wurzelverzeichnis erstellen möchte. Siehe auch https://bitbucket.org/site/master/issue/6315/relative-urls-in-readmemd-files-only-work >> Jetzt muss man die Doku nur noch ordentlich strukturieren. Doxygen >> bietet auch Markdown an. Vielleicht ließe sich das ja für >> Nicht-Klassendoku verwenden. Hilfreich finde ich auch die Möglichkeit, >> verwaiste Querverweise zu finden. >> > > Hier fehlen mir vor der Klassendokumentation vor allem die gut > strukturierten und übersichtlichen Einführungsseiten, die zu Tutorials > und Grundkonzepten führen. Ich weiss nicht, wie gut sich das mit Doxygen > wirklich machen lässt. Ich hatte für sowas vor einiger Zeit mal Sphinx > entdeckt, das ist aber auch aus dem Python Umfeld. > > http://sphinx-doc.org/index.html > > Dafür gibt es aber ein Plugin/Extension (Breathe), das mit Hilfe von > Doxygen den C++ Code durchsucht und indiziert: > > https://michaeljones.github.io/breathe/ > > Das ist vielleicht eine Möglichkeit, falls Doxygen keinen ordentlichen > Support für Dokumentation außerhalb der Klassendoku bietet. Dort scheint > auch reStructuredText statt Markdown benutzt zu werden, was mir auch > recht sein soll. Doxygen unterstützt auch Markdown-Dateien und zumindest Links aus der API heraus in diese Dokumente. Es bietet neben der allgemeinen Startseite die Trennung in Module an. Für jedes Modul kann man eine eigene Einstiegsseite erstellen und weitere beliebige Unterseiten. Dort kann man zum Beispiel auch die Beispiele verlinken. Beispiele benötigen m.E. keine API-Dokumentation. Daher sollten die dort auch nicht auftauchen. Mindestens zwei Dinge stören mich an Doxygen: - Die schwache Suchfunktion und die unübersichtliche Navigation - Man kann Makros nicht einzelnen Klassen zuordnen, höchstens Modulen Aber die Entwickler scheinen recht aktiv zu sein. Daher wäre die Frage, ob das mit Sphinx+Breathe+Doxygen besser geht. Breathe kannte ich noch nicht. Danke für den Link. Die Doku von Breathe ist hübsch anzusehen. Würdest Du das Paket mal für REFLEX evaluieren? Wenn Zeit ist, spiele ich das mal für Doxygen durch. Richard
