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

Samstag 19. Mai 2007, 18:34

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
Administrator
Beiträge: 16024
Registriert: Freitag 20. Juni 2003, 16:30
Kontaktdaten:

Samstag 19. Mai 2007, 18:45

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 Modvoice
rafael
User
Beiträge: 189
Registriert: Mittwoch 26. Juli 2006, 16:13

Samstag 19. Mai 2007, 19:17

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:

Samstag 19. Mai 2007, 19:49

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: 4871
Registriert: Donnerstag 20. Juli 2006, 23:06
Wohnort: Berlin

Samstag 19. Mai 2007, 20:32

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:

Samstag 19. Mai 2007, 23:19

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

Samstag 19. Mai 2007, 23:29

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

Sonntag 20. Mai 2007, 11:20

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
Moderator
Beiträge: 8483
Registriert: Dienstag 10. August 2004, 09:40
Wohnort: duisburg
Kontaktdaten:

Sonntag 20. Mai 2007, 11:27

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...

CMS in Python: http://www.pylucid.org
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:

Sonntag 20. Mai 2007, 13:37

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:

Sonntag 20. Mai 2007, 14:54

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
Administrator
Beiträge: 16024
Registriert: Freitag 20. Juni 2003, 16:30
Kontaktdaten:

Sonntag 20. Mai 2007, 15:09

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 Modvoice
Benutzeravatar
gerold
Python-Forum Veteran
Beiträge: 5555
Registriert: Samstag 28. Februar 2004, 22:04
Wohnort: Oberhofen im Inntal (Tirol)
Kontaktdaten:

Sonntag 20. Mai 2007, 15:12

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

Sonntag 20. Mai 2007, 15:36

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

Sonntag 20. Mai 2007, 16:11

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/
Antworten