So könnte die Python-Dokumentation aussehen

Stellt hier eure Projekte vor.
Internetseiten, Skripte, und alles andere bzgl. Python.
Benutzeravatar
birkenfeld
Python-Forum Veteran
Beiträge: 1603
Registriert: Montag 20. März 2006, 15:29
Wohnort: Die aufstrebende Universitätsstadt bei München

Für die, die python-dev nicht mitlesen: ich habe etwas mit der Doku herumexperimentiert mit dem Ziel, von LaTeX wegzukommen und der Möglichkeit, neue Features einzubauen (Kommentarfunktion etc.). Das Ergebnis sieht man unter

http://pydoc.gbrandl.de,

die Quellen sind dabei nicht mehr LaTeX, sondern reStructuredText.

Hier der Link zum Post auf python-dev: http://article.gmane.org/gmane.comp.python.devel/88197
Dann lieber noch Vim 7 als Windows 7.

http://pythonic.pocoo.org/
Leonidas
Python-Forum Veteran
Beiträge: 16025
Registriert: Freitag 20. Juni 2003, 16:30
Kontaktdaten:

Wow, it rocks :)

+1 dafür, wobei ich aber einige Fehler in der Übersetzung von LaTeX nach rst gefunden habe. Aber das sind Kleinigkeiten.
My god, it's full of CARs! | Leonidasvoice vs (former) Modvoice
rafael
User
Beiträge: 189
Registriert: Mittwoch 26. Juli 2006, 16:13

Yeah, echt cool und viel leserfreundlicher als die jetzige Doku...

Hoffe, dass die Doku darauf upgedatet wird.
Benutzeravatar
gerold
Python-Forum Veteran
Beiträge: 5555
Registriert: Samstag 28. Februar 2004, 22:04
Wohnort: Oberhofen im Inntal (Tirol)
Kontaktdaten:

Hallo birkenfeld!

Ich persönlich mag LaTeX nicht bzw. ich kann damit nicht arbeiten. Aber fast jeder Python-Programmierer hat schon mal etwas mit reStructuredText gemacht.

Wenn die Dokumentation endlich in reStructuredText geschrieben werden würde, dann könnte man viel leichter an der Dokumentation mithelfen und mehr Beispiele rein bringen.

Deshalb denke ich, dass das ein rießiger Schritt in die richtige Richtung wäre. 8)

mfg
Gerold
:-)

PS: Die Schriftart der Codebeispiele müsste man so anpassen, dass diese auch unter Windows und mit TFT noch gut lesbar sind und nicht so verschwimmen. Das ist auch ein Problem bei Lodgeit (paste.pocoo.org). Aber das lässt sich bestimmt lösen. :-)
Zuletzt geändert von gerold am Samstag 19. Mai 2007, 21:19, insgesamt 1-mal geändert.
http://halvar.at | Kleiner Bascom AVR Kurs
Wissen hat eine wunderbare Eigenschaft: Es verdoppelt sich, wenn man es teilt.
EyDu
User
Beiträge: 4881
Registriert: Donnerstag 20. Juli 2006, 23:06
Wohnort: Berlin

Eine gewisse Ähnlichkeit mit der Django-Dokumentation lässt sich aber nicht abstreiten :D

Aber das Ergebnis gefällt mir ganz gut. Nur der "Jump to Top"-Button passt nicht so recht ins Layout. Zumindest ich habe immer diesen starken Drang, nach rechts unten zu schauen :-)
mitsuhiko
User
Beiträge: 1790
Registriert: Donnerstag 28. Oktober 2004, 16:33
Wohnort: Graz, Steiermark - Österreich
Kontaktdaten:

EyDu hat geschrieben:Eine gewisse Ähnlichkeit mit der Django-Dokumentation lässt sich aber nicht abstreiten :D
Liegt daran, dass wir einfach das Django grün nach blau umgewandelt und die Sidebar auf die andere Seite geschoben haben. :-)
Aber das Ergebnis gefällt mir ganz gut. Nur der "Jump to Top"-Button passt nicht so recht ins Layout. Zumindest ich habe immer diesen starken Drang, nach rechts unten zu schauen :-)
Joa. Da muss noch nachgebessert werden.
TUFKAB – the user formerly known as blackbird
Benutzeravatar
birkenfeld
Python-Forum Veteran
Beiträge: 1603
Registriert: Montag 20. März 2006, 15:29
Wohnort: Die aufstrebende Universitätsstadt bei München

gerold hat geschrieben: Ich persönlich mag LaTeX nicht bzw. ich kann damit nicht arbeiten.
Ich bin dagegen ein großer LaTeX-Fan, und zwar da, wo es seine Stärken ausspielen kann (Erstellung von wissenschaftlichen Dokumenten). Zum Dokumentieren von Software ist es nie gedacht gewesen.
Aber fast jeder Python-Programmierer hat schon mal etwas mit reStructuredText gemacht.

Wenn die Dokumentation endlich in reStructuredText geschrieben werden würde, dann könnte man viel leichter an der Dokumentation mithelfen und mehr Beispiele rein bringen.
Genau das war auch mein Gedanke und ist einer der Gründe, warum ich das durchziehe.
PS: Die Schriftart der Codebeispiele müsste man so anpassen, dass diese auch unter Windows und mit TFT noch gut lesbar sind und nicht so verschwimmen. Das ist auch ein Problem bei Lodgeit (paste.pocoo.org). Aber das lässt sich bestimmt lösen. :-)
Jo, das kommt davon, wenn man nicht unter Windows testet.
Dann lieber noch Vim 7 als Windows 7.

http://pythonic.pocoo.org/
rafael
User
Beiträge: 189
Registriert: Mittwoch 26. Juli 2006, 16:13

Zufällig gefunden:
Python's library reference documentation
is written using LaTeX, like it or not, and it's not going to change
any time soon. (*If* and *when* it changes, it's probably going to be
something XMLish. But since XML is so more verbose than LaTeX, I'm
not sure there's much of a point to this, at least unless bitrot takes
the LaTeX toolchain away from us.)
http://mail.python.org/pipermail/python ... 22212.html
Benutzeravatar
jens
Python-Forum Veteran
Beiträge: 8502
Registriert: Dienstag 10. August 2004, 09:40
Wohnort: duisburg
Kontaktdaten:

Die Anker sind nich so gut positioniert. Bzw. es gibt anscheinend zwei. Einer für den eigentlichen Text:
http://pydoc.gbrandl.de/reference/stdty ... index-1039
und einmal ein vernünftiger der auch richtig bei der Überschrift positioniert ist:
http://pydoc.gbrandl.de/reference/stdty ... operations

Im Index wird allerdings der erste benutzt, obwohl der zweite Anker besser wäre...

GitHub | Open HUB | Xing | Linked in
Bitcoins to: 1JEgSQepxGjdprNedC9tXQWLpS424AL8cd
Benutzeravatar
veers
User
Beiträge: 1219
Registriert: Mittwoch 28. Februar 2007, 20:01
Wohnort: Zürich (CH)
Kontaktdaten:

Sieht nett aus, wirkt auch übersichtlicher als die derzeitige Doku. Andererseits komme ich zumindest als Leser auch gut mit der derzeitigen Doku klar. Wie es mit der wartbarkeit aussieht weis ich nicht.
birkenfeld hat geschrieben:
gerold hat geschrieben: Ich persönlich mag LaTeX nicht bzw. ich kann damit nicht arbeiten.
Ich bin dagegen ein großer LaTeX-Fan, und zwar da, wo es seine Stärken ausspielen kann (Erstellung von wissenschaftlichen Dokumenten). Zum Dokumentieren von Software ist es nie gedacht gewesen.
Signed.
EnTeQuAk
User
Beiträge: 986
Registriert: Freitag 21. Juli 2006, 15:03
Wohnort: Berlin
Kontaktdaten:

Endlich ist das ganze etwas farbiger. So, wie ich das mitbekomme habe habt ihr ja eine ganze Menge Komponenten wirklich gut zusammengeschweißt. (wenn das hier jetzt die Arbeit, von `repydoc` ist)

Ist wirklich gut gelungen. Mich würde es sehr freuen, wenn das wirklich demnächst durchgeboxt wird.

Wird man dann auch die alten Dokus aktualisieren oder nur neuere (ab 2.5.1+ bzw. 2.6+)?


MfG EnTeQuAk
Leonidas
Python-Forum Veteran
Beiträge: 16025
Registriert: Freitag 20. Juni 2003, 16:30
Kontaktdaten:

EnTeQuAk hat geschrieben:Endlich ist das ganze etwas farbiger. So, wie ich das mitbekomme habe habt ihr ja eine ganze Menge Komponenten wirklich gut zusammengeschweißt. (wenn das hier jetzt die Arbeit, von `repydoc` ist)
Nein, das ist eher ein modifiziertes Sphinx (welches ursprünglich für den Pocoo-Internen Gebrauch entstanden ist), also Docutils + Pygments + Jinja. Den Quellcode gibts nun in der docutils Sandbox.

Ich der Python-Dev-Diskussion sind einige wirklich gute Ideen gefallen. Aber dieses Quick-Dispatch ist zumindest mit den Modulen schon jetzt möglich, dank Formatting-Characters in den Bookmarks.
My god, it's full of CARs! | Leonidasvoice vs (former) Modvoice
Benutzeravatar
gerold
Python-Forum Veteran
Beiträge: 5555
Registriert: Samstag 28. Februar 2004, 22:04
Wohnort: Oberhofen im Inntal (Tirol)
Kontaktdaten:

Hallo!

Ich habe mir die Zeit genommen und die Original-Doku mit der neuen Doku verglichen. Dabei ist mir aufgefallen, dass sich die Original-Doku leichter lesen lässt. Das führe ich hauptsächlich auf die Farbgebung, die Schriftgestaltung und die in der alten Doku so einfach gehaltenen Navigationsleisten oben und unten zurück.

Ich begrüße natürlich die Möglichkeit, die Doku mit reStructuredText zu erweitern und auch eine Suche war längst mal fällig, aber ich halte das Layout (Farbgebung, Seitenaufbau, und sogar die Pfeile zur Navigation) der Original-Doku für klarer, einfacher und freundlicher. Weniger (Farbe) ist mehr.

lg
Gerold
:-)

PS: Und schon wieder bin ich der Böse. :roll:
http://halvar.at | Kleiner Bascom AVR Kurs
Wissen hat eine wunderbare Eigenschaft: Es verdoppelt sich, wenn man es teilt.
BlackJack

LaTeX ist nie für Programmdokumentation gedacht gewesen? Das lasst aber mal nicht Knuth hören. ;-)

Ick sach nur WEB und CWEB…
Benutzeravatar
birkenfeld
Python-Forum Veteran
Beiträge: 1603
Registriert: Montag 20. März 2006, 15:29
Wohnort: Die aufstrebende Universitätsstadt bei München

rafael hat geschrieben:
Python's library reference documentation
is written using LaTeX, like it or not, and it's not going to change
any time soon. (*If* and *when* it changes, it's probably going to be
something XMLish. But since XML is so more verbose than LaTeX, I'm
not sure there's much of a point to this, at least unless bitrot takes
the LaTeX toolchain away from us.)
So schnell ändern sich die Dinge :)
jens hat geschrieben: Die Anker sind nich so gut positioniert. Bzw. es gibt anscheinend zwei. Einer für den eigentlichen Text:
http://pydoc.gbrandl.de/reference/stdty ... index-1039
und einmal ein vernünftiger der auch richtig bei der Überschrift positioniert ist:
http://pydoc.gbrandl.de/reference/stdty ... operations

Im Index wird allerdings der erste benutzt, obwohl der zweite Anker besser wäre...
Ja, die Index-Anker werden durch eigene Direktiven gesetzt, während die Überschriften-Anker von docutils selbst generiert werden. Man kann nun schon den Indexeintrag auf die ihn enthaltende Überschrift setzen, aber dann verliert man die Information über die genaue Stelle, wo das Stichwort vorkommt. Und bei langen Kapiteln ist das doch recht wichtig.
Leonidas hat geschrieben:
Endlich ist das ganze etwas farbiger. So, wie ich das mitbekomme habe habt ihr ja eine ganze Menge Komponenten wirklich gut zusammengeschweißt. (wenn das hier jetzt die Arbeit, von `repydoc` ist)
Nein, das ist eher ein modifiziertes Sphinx (welches ursprünglich für den Pocoo-Internen Gebrauch entstanden ist), also Docutils + Pygments + Jinja. Den Quellcode gibts nun in der docutils Sandbox.
Eigentlich hat Ente recht -- das, was man dort sieht, ist "repydoc". Den Namen "Sphinx" hab ich nur "geklaut", weil er besser klingt.
gerold hat geschrieben: Ich habe mir die Zeit genommen und die Original-Doku mit der neuen Doku verglichen. Dabei ist mir aufgefallen, dass sich die Original-Doku leichter lesen lässt. Das führe ich hauptsächlich auf die Farbgebung, die Schriftgestaltung und die in der alten Doku so einfach gehaltenen Navigationsleisten oben und unten zurück.

Ich begrüße natürlich die Möglichkeit, die Doku mit reStructuredText zu erweitern und auch eine Suche war längst mal fällig, aber ich halte das Layout (Farbgebung, Seitenaufbau, und sogar die Pfeile zur Navigation) der Original-Doku für klarer, einfacher und freundlicher. Weniger (Farbe) ist mehr.

PS: Und schon wieder bin ich der Böse.
Aber überhaupt nicht. Ich kann deine Gründe sehr gut nachvollziehen, und ich have vor, ein alternatives Stylesheet einzubauen, was das Look-and-Feel der alten Version nachbildet. So hat jeder etwas davon. :)
BlackJack hat geschrieben: LaTeX ist nie für Programmdokumentation gedacht gewesen? Das lasst aber mal nicht Knuth hören. Wink

Ick sach nur WEB und CWEB…
Oder Haskells Literate Programming, da hast du völlig recht. Da ist meine eigene Meinung mit mir durchgegangen. :)
Dann lieber noch Vim 7 als Windows 7.

http://pythonic.pocoo.org/
Benutzeravatar
gerold
Python-Forum Veteran
Beiträge: 5555
Registriert: Samstag 28. Februar 2004, 22:04
Wohnort: Oberhofen im Inntal (Tirol)
Kontaktdaten:

birkenfeld hat geschrieben:Ich kann deine Gründe sehr gut nachvollziehen, und ich have vor, ein alternatives Stylesheet einzubauen, was das Look-and-Feel der alten Version nachbildet. So hat jeder etwas davon. :)
Hallo birkenfeld!

Ich bin sprachlos! :D Vielen Dank und weiter so!

lg
Gerold
:-)
http://halvar.at | Kleiner Bascom AVR Kurs
Wissen hat eine wunderbare Eigenschaft: Es verdoppelt sich, wenn man es teilt.
Benutzeravatar
Rebecca
User
Beiträge: 1662
Registriert: Freitag 3. Februar 2006, 12:28
Wohnort: DN, Heimat: HB
Kontaktdaten:

Ich muss Gerold in einigen Punkten zustimmen: Ich finde die Farbe der Links im Text (blau auf weiss) relativ kontrastarm. Die Pfeile zum Blaettern in der alten Version sprangen mehr ins Auge als die Verweise jetzt.

Den Pfeil nach oben zum Seitenanfang finde ich ziemlich genial, nachdem ich ihn erstmal entdeckt habe. Ers ist relativ schwer zu erkennen, finde ich.

Die Sidebar finde ich klasse, sowas hat mir bisher gefehlt. Bisher bin ich naemlich sehr oft immer wieder per Browserlink zur Startseite zurueckgekehrt, um das Inhaltsverzeichnis zu sehen oder die Suche zu benutzen...

In der Darstellung der Suchergebnisse tauchen noch ziemlich oft HTML/...-Markups auf... Oh, ich sehe gerade, der Module Index ist jetzt nach Themen sortiert -- sehr gut.

Mmh, an dieser Stelle waere jetzt ein Daumen-Hoch- oder Kniefall-Smiley angebracht. :)
EnTeQuAk
User
Beiträge: 986
Registriert: Freitag 21. Juli 2006, 15:03
Wohnort: Berlin
Kontaktdaten:

Mmh, an dieser Stelle waere jetzt ein Daumen-Hoch- oder Kniefall-Smiley angebracht. Smile
Bild
:P :D 8) :lol:

MfG EnTeQuAk
mitsuhiko
User
Beiträge: 1790
Registriert: Donnerstag 28. Oktober 2004, 16:33
Wohnort: Graz, Steiermark - Österreich
Kontaktdaten:

Rebecca hat geschrieben:Den Pfeil nach oben zum Seitenanfang finde ich ziemlich genial, nachdem ich ihn erstmal entdeckt habe. Ers ist relativ schwer zu erkennen, finde ich.
Ich hab lokal jetzt eine bessere Lösung, hab aber noch keinen Zugriff auf das neue Repository.
In der Darstellung der Suchergebnisse tauchen noch ziemlich oft HTML/...-Markups auf... Oh, ich sehe gerade, der Module Index ist jetzt nach Themen sortiert -- sehr gut.
Das mit dem HTML Markup in der Javascript Suche ist neu. Das ist mir auch schon aufgefallen. Schau ich mir gleich an, der Suchindex wird nämlich wohl auch für die Python Suche verwendet werden.
TUFKAB – the user formerly known as blackbird
Leonidas
Python-Forum Veteran
Beiträge: 16025
Registriert: Freitag 20. Juni 2003, 16:30
Kontaktdaten:

Rebecca hat geschrieben:Den Pfeil nach oben zum Seitenanfang finde ich ziemlich genial, nachdem ich ihn erstmal entdeckt habe. Ers ist relativ schwer zu erkennen, finde ich.
Ja er ist zwar lustig (hab ihn auch erst gesehen, als hier darauf hingewiesen wurde), aber igendwie habe ich nie den Sinn von Go-To-Top-Links nicht gesehen. Ganz oben komme ich mit ``1G``.. nein, stopp, mit ``Bild Hoch`` ;) Habe ich bisher aber auch noch nicht so besonders oft gebraucht, Typeahead-Suche finde ich wesentlich praktischer.
My god, it's full of CARs! | Leonidasvoice vs (former) Modvoice
Antworten