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
So könnte die Python-Dokumentation aussehen
- birkenfeld
- Python-Forum Veteran
- Beiträge: 1603
- Registriert: Montag 20. März 2006, 15:29
- Wohnort: Die aufstrebende Universitätsstadt bei München
-
- 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.
+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
- 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.
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.
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.
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.
Wissen hat eine wunderbare Eigenschaft: Es verdoppelt sich, wenn man es teilt.
Eine gewisse Ähnlichkeit mit der Django-Dokumentation lässt sich aber nicht abstreiten
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
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
-
- User
- Beiträge: 1790
- Registriert: Donnerstag 28. Oktober 2004, 16:33
- Wohnort: Graz, Steiermark - Österreich
- Kontaktdaten:
Liegt daran, dass wir einfach das Django grün nach blau umgewandelt und die Sidebar auf die andere Seite geschoben haben.EyDu hat geschrieben:Eine gewisse Ähnlichkeit mit der Django-Dokumentation lässt sich aber nicht abstreiten
Joa. Da muss noch nachgebessert werden.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
TUFKAB – the user formerly known as blackbird
- birkenfeld
- Python-Forum Veteran
- Beiträge: 1603
- Registriert: Montag 20. März 2006, 15:29
- Wohnort: Die aufstrebende Universitätsstadt bei München
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.gerold hat geschrieben: Ich persönlich mag LaTeX nicht bzw. ich kann damit nicht arbeiten.
Genau das war auch mein Gedanke und ist einer der Gründe, warum ich das durchziehe.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.
Jo, das kommt davon, wenn man nicht unter Windows testet.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.
Zufällig gefunden:
http://mail.python.org/pipermail/python ... 22212.htmlPython'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.)
- 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...
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...
- 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.
Signed.birkenfeld hat geschrieben: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.gerold hat geschrieben: Ich persönlich mag LaTeX nicht bzw. ich kann damit nicht arbeiten.
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
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
-
- Python-Forum Veteran
- Beiträge: 16025
- Registriert: Freitag 20. Juni 2003, 16:30
- Kontaktdaten:
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.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)
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
- 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.
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.
http://halvar.at | Kleiner Bascom AVR Kurs
Wissen hat eine wunderbare Eigenschaft: Es verdoppelt sich, wenn man es teilt.
Wissen hat eine wunderbare Eigenschaft: Es verdoppelt sich, wenn man es teilt.
LaTeX ist nie für Programmdokumentation gedacht gewesen? Das lasst aber mal nicht Knuth hören.
Ick sach nur WEB und CWEB…
Ick sach nur WEB und CWEB…
- birkenfeld
- Python-Forum Veteran
- Beiträge: 1603
- Registriert: Montag 20. März 2006, 15:29
- Wohnort: Die aufstrebende Universitätsstadt bei München
So schnell ändern sich die Dingerafael 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.)
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.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...
Eigentlich hat Ente recht -- das, was man dort sieht, ist "repydoc". Den Namen "Sphinx" hab ich nur "geklaut", weil er besser klingt.Leonidas hat geschrieben: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.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)
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.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.
Oder Haskells Literate Programming, da hast du völlig recht. Da ist meine eigene Meinung mit mir durchgegangen.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…
- gerold
- Python-Forum Veteran
- Beiträge: 5555
- Registriert: Samstag 28. Februar 2004, 22:04
- Wohnort: Oberhofen im Inntal (Tirol)
- Kontaktdaten:
Hallo birkenfeld!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.
Ich bin sprachlos! 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.
Wissen hat eine wunderbare Eigenschaft: Es verdoppelt sich, wenn man es teilt.
- 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.
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.
Mmh, an dieser Stelle waere jetzt ein Daumen-Hoch- oder Kniefall-Smiley angebracht. Smile
MfG EnTeQuAk
-
- User
- Beiträge: 1790
- Registriert: Donnerstag 28. Oktober 2004, 16:33
- Wohnort: Graz, Steiermark - Österreich
- Kontaktdaten:
Ich hab lokal jetzt eine bessere Lösung, hab aber noch keinen Zugriff auf das neue Repository.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.
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.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.
TUFKAB – the user formerly known as blackbird
-
- Python-Forum Veteran
- Beiträge: 16025
- Registriert: Freitag 20. Juni 2003, 16:30
- Kontaktdaten:
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.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.
My god, it's full of CARs! | Leonidasvoice vs (former) Modvoice