ZFX + Developia

Alexander Kornrumpf hat geschrieben:

Jonathan hat geschrieben:Ich habe noch keine einzige Python-Bibliothek mit benutzbarer Dokumentation gefunden. Ich muss absolut jeden kleinen Scheiß jedes mal in Google eintippen. Und das nervt, insbesondere weil es unnötig ist.

Wait, what?

Musste gerade nochmal daran denken, aus gegebenen Anlass. Wie gesagt, ist vielleicht nicht alles objektiv. Hier ein Beispiel:

https://pythonhosted.org/pyserial/index.html

Und hier die Probleme:
1. Die Farben (ok ok, aber es sieht einfach hässlich aus...)
2. Sphinx-Dokumentationen sind Bücher nachempfunden. Bibliotheksdokumentationen sind aber keine linearen Medien, kein Mensch liest das von vorne bis hinten durch. In der Regel will ich über eine bestimmte Klasse ein bestimmtes Detail nachschlagen, da ist der 'next' Link, der mich zur alphabetisch nächsten Klasse bringt einfach nur absurd.
3. Merkwürdiges Navigationsmenü. Am Anfang bekomme ich eine Inhaltsübersicht, das ist ansich ganz gut. Aber klicke ich einen Teil an, habe ich links in der Leiste nur noch Themen des aktuellen Kapitels. Da Kapitel oft lang sind, sieht das immer noch umfangreich aus, aber ich finde oft nicht das was ich suche, weil mir nur 1/10 der Doku angezeigt wird, was nicht immer direkt ersichtlich ist.
4. Endlos lange Seiten. In diesem Beispiel sind alle Klassen in einem Kapitel dokumentiert, untereinander. Oft will ich wissen, wie Funktionen miteinander in Bezug stehen, scrolle also ein wenig hoch und runter. Und schwups, find ich nicht mehr zurück weil diese verdammten Seiten einfach unendlich lang sind.
5. Inkosequente Verlinkung. Oft tauchen im Text oder Codebeispielen Objekte dieser Bibliothek auf, man kann aber nicht drauf klicken um direkt zur Dokumentation zu kommen.
6. Keine Klassenübersicht. Es werden direkt alle Member inklusiv vollständiger Dokumentation aufgelistet. Wenn man nur mal kurz gucken will, welche Funktionen es so gibt, muss man direkt endlos scrollen (was gefährlich ist, weil die Seiten so verdammt lang sind).

Mir würde bestimmt noch mehr einfallen, aber ich glaube, das hier reicht erstmal. Übrigens macht z.B. cppreference.com quasi all diese Punkte besser/richtig. So muss Dokumentation aussehen.

(Wie man gemerkt hat, kritisiere ich die Form, nicht den Inhalt. Mit etwas suchen findet man oft die nötigen Informationen, von daher ist es ok. Aber ich denke einfach, das Sphinx eine einzige Katastrophe ist und es jammerschade ist, dass so viel Python-Kram das benutzt. Vielleicht würde ich sogar sagen, dass sich Sphinx zu Python verhält, wie CMake zu C++ - und meine Meinung zu CMake habe ich ja hier schon oft genug ausgedrückt :D)

Jonathan hat geschrieben:Wie man gemerkt hat, kritisiere ich die Form, nicht den Inhalt. Mit etwas suchen findet man oft die nötigen Informationen, von daher ist es ok.

Fair enough.

...
In der Regel will ich über eine bestimmte Klasse ein bestimmtes Detail nachschlagen, da ist der 'next' Link, der mich zur alphabetisch nächsten Klasse bringt einfach nur absurd.
...
Endlos lange Seiten. In diesem Beispiel sind alle Klassen in einem Kapitel dokumentiert, untereinander.

Diese beiden Punkte widersprechen einander allerdings.