So könnte die Python-Dokumentation aussehen

Stellt hier eure Projekte vor.
Internetseiten, Skripte, und alles andere bzgl. Python.
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
mitsuhiko
User
Beiträge: 1790
Registriert: Donnerstag 28. Oktober 2004, 16:33
Wohnort: Graz, Steiermark - Österreich
Kontaktdaten:

Jetzt gibts auch die "interaktive" Version zum Testen: http://pydoc.gbrandl.de:3000/

Kurzzusammenfassung: rät URLs (ähnlich wie bei php.net), hat Kommentare, man kann mal testweise die Sidebar nach rechts bugsieren, Feeds, Antispam und ein Adminpanel unter http://pydoc.gbrandl.de:3000/admin/

Zugangsdaten sind testuser:password

Viel Spaß beim Testen :-)
TUFKAB – the user formerly known as blackbird
apollo13
User
Beiträge: 827
Registriert: Samstag 5. Februar 2005, 17:53

Willst du mal nen Anker setzen, dass unter "Moderate Comments -> View" gleich hinuter zu dem/den Comments gesprungen wird?
Y0Gi
User
Beiträge: 1454
Registriert: Freitag 22. September 2006, 23:05
Wohnort: ja

Insgesamt: Gute Arbeit! Etwas gewöhnungsbedürftig, aber das ist bei Änderungen ja nunmal oft so.

Ein paar Dinge, die mir so auffallen:

- Die Beschreibungen zu den Hauptlinks der Startseite überschneiden sich an einigen Stellen mit dem Titel darüber, was es schlechter lesbar macht. Da könnte ein leicht größerer Abstand einiges bewirken.

- Auch wenn es nett einheitlich aussieht: Die Klammern sind überflüssig und der Verzicht auf diese trägt ebenfalls zu besserer Lesbarkeit bei. Eine Option wäre zur Not, die Klammern per CSS mit :before und :after hinzuzufügen, damit man sie zumindest für sich selbst deaktivieren kann.

- Ich persönlich benutze den "Global Module Index" *sehr* viel. Der ist mir fast ein bisschen zu weit unten, auch wenn ich mit einem schlanken Browserfenster noch nicht scrollen muss. Fraglich, wie weit die (durchaus sinnvolle) Gruppierung so ideal ist, aber sowas wie "Macintosh Library Modules" und "Distributing/Documenting Python Modules" ist IMHO etwas, das man sicherlich weitaus seltener liest als den GMI - und deswegen ist hier die Reihenfolge für mich sehr suboptimal. Zum Vergleich: Ich benutze sehr viel die .chm-Doku (auch unter Linux; Index und Suchfunktion sind doch irgendwie praktischer als über einen Webbrowser) und dort (wie auch im Web) kommt der GMI an sehr früher Stelle - zu Recht. Bitte das nochmal überdenken.

- Warum müssen die Feeds unbedingt RSS sein? ATOM 1.0 ist der (einzige?) abgesegnete, saubere Standard und jeder halbwegs brauchbare Client kann es ebenso lesen. RSS ist nur ein inkompatibler Formatdschungel mit zahlreichen Problemen, die ATOM löst. Die gängigen ATOM vs. RSS-Vergleiche sollten bekannt oder ansonsten leicht auffindbar sein.
mitsuhiko
User
Beiträge: 1790
Registriert: Donnerstag 28. Oktober 2004, 16:33
Wohnort: Graz, Steiermark - Österreich
Kontaktdaten:

Y0Gi hat geschrieben: - Die Beschreibungen zu den Hauptlinks der Startseite überschneiden sich an einigen Stellen mit dem Titel darüber, was es schlechter lesbar macht. Da könnte ein leicht größerer Abstand einiges bewirken.
Hast du da einen Screenshot dazu? Hier passt das nämlich.
- Auch wenn es nett einheitlich aussieht: Die Klammern sind überflüssig und der Verzicht auf diese trägt ebenfalls zu besserer Lesbarkeit bei. Eine Option wäre zur Not, die Klammern per CSS mit :before und :after hinzuzufügen, damit man sie zumindest für sich selbst deaktivieren kann.
Welche Klammern?
- Ich persönlich benutze den "Global Module Index" *sehr* viel. Der ist mir fast ein bisschen zu weit unten, auch wenn ich mit einem schlanken Browserfenster noch nicht scrollen muss. Fraglich, wie weit die (durchaus sinnvolle) Gruppierung so ideal ist, aber sowas wie "Macintosh Library Modules" und "Distributing/Documenting Python Modules" ist IMHO etwas, das man sicherlich weitaus seltener liest als den GMI - und deswegen ist hier die Reihenfolge für mich sehr suboptimal. Zum Vergleich: Ich benutze sehr viel die .chm-Doku (auch unter Linux; Index und Suchfunktion sind doch irgendwie praktischer als über einen Webbrowser) und dort (wie auch im Web) kommt der GMI an sehr früher Stelle - zu Recht. Bitte das nochmal überdenken.
GMI kann man sicher raufbewegen, ist aber zusätzlich auch in der Topbar oben rechts. CHM müssen wir uns auch noch was einfallen lassen.
- Warum müssen die Feeds unbedingt RSS sein? ATOM 1.0 ist der (einzige?) abgesegnete, saubere Standard und jeder halbwegs brauchbare Client kann es ebenso lesen. RSS ist nur ein inkompatibler Formatdschungel mit zahlreichen Problemen, die ATOM löst. Die gängigen ATOM vs. RSS-Vergleiche sollten bekannt oder ansonsten leicht auffindbar sein.
Das ist ganz einfach. RSS ist schnell implementiert, wird von jedem Client unterstützt, funktioniert auch ohne DTD oder xmlns. Ich sehe ein, dass RSS ein scheiß Format ist, aber für so einfach Feeds ist es ideal.
TUFKAB – the user formerly known as blackbird
Y0Gi
User
Beiträge: 1454
Registriert: Freitag 22. September 2006, 23:05
Wohnort: ja

Guckst du:

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

Y0Gi hat geschrieben:Fraglich, wie weit die (durchaus sinnvolle) Gruppierung so ideal ist, aber sowas wie "Macintosh Library Modules" und "Distributing/Documenting Python Modules" ist IMHO etwas, das man sicherlich weitaus seltener liest als den GMI - und deswegen ist hier die Reihenfolge für mich sehr suboptimal.
Ich benutze im GMI immer die Type-ahead-Suche oder setze mir gleich ein Bookmark mit Formattern (%s) im Browser, das funktioniert sehr gut.
My god, it's full of CARs! | Leonidasvoice vs (former) Modvoice
pythonist
User
Beiträge: 40
Registriert: Sonntag 14. Mai 2006, 17:28

Also erst mal ich finds genial das sich das was tut, weil die aktuelle Dokumentation ist alles Andere als zeitgemäß.

Ich find aber die Alte auch leichter zu lesen, wobei man das sicher durch anpassen der Farben Schriften änder kann.

Wichtig für ne neue Doku find ich:
  • Gute Kommentarfunktion weil man so relativ schnell vile Code-Beispiele bekommt
    Möglichkeit der Übersetzung in ander Sprachen damit die möglichkeit besteht die Doku wenigstens Teilweiße in ander Sprachen zu übersetzen
    Vieleicht noch Quellcode-Ansicht der einzelnen Module
Ich hoffe das Feedback hilft n bisl.
Und danke da ihr das anpackt.

pythonist
Benutzeravatar
jens
Python-Forum Veteran
Beiträge: 8502
Registriert: Dienstag 10. August 2004, 09:40
Wohnort: duisburg
Kontaktdaten:

pythonist hat geschrieben:
  • Vieleicht noch Quellcode-Ansicht der einzelnen Module
Das würde ich allerdings auch super finden!

GitHub | Open HUB | Xing | Linked in
Bitcoins to: 1JEgSQepxGjdprNedC9tXQWLpS424AL8cd
Benutzeravatar
Quash
User
Beiträge: 9
Registriert: Donnerstag 5. Juli 2007, 01:53

Sehr gut, gefällt mir!
Benutzeravatar
jens
Python-Forum Veteran
Beiträge: 8502
Registriert: Dienstag 10. August 2004, 09:40
Wohnort: duisburg
Kontaktdaten:

Ist es normal das die Suche noch (?) nicht geht?

bsp:
http://docs.python.org/dev/search.html? ... a=whatsnew

GitHub | Open HUB | Xing | Linked in
Bitcoins to: 1JEgSQepxGjdprNedC9tXQWLpS424AL8cd
rafael
User
Beiträge: 189
Registriert: Mittwoch 26. Juli 2006, 16:13

jens hat geschrieben:Ist es normal das die Suche noch (?) nicht geht?

bsp:
http://docs.python.org/dev/search.html? ... a=whatsnew
Bei mir klappt dein Link.
Die Suchergebnisse kommen aber erst nach, da IIRC, die Suche in Javascript geschrieben ist.
Benutzeravatar
jens
Python-Forum Veteran
Beiträge: 8502
Registriert: Dienstag 10. August 2004, 09:40
Wohnort: duisburg
Kontaktdaten:

Ah, jo... NoScript ;)

IMHO gehört da ein <noscript>Please enable Javascript</noscript> o.ä. hin ;)

GitHub | Open HUB | Xing | Linked in
Bitcoins to: 1JEgSQepxGjdprNedC9tXQWLpS424AL8cd
Antworten