Die neue Python-Dokumentation

Presented at µPy.

Transcript

1. Die neue Python-Dokumentation
   Marek Kubica
   24. Januar 2008
   

   View Slide

2. Der aktuelle Stand
   Umfassende Dokumentation mit L
   AT
   EXgeschrieben
   

   View Slide

3. Der aktuelle Stand
   Umfassende Dokumentation mit L
   AT
   EXgeschrieben
   In vielen Formaten verfügbar (HTML, PDF, PostScript)
   

   View Slide

4. Der aktuelle Stand
   Umfassende Dokumentation mit L
   AT
   EXgeschrieben
   In vielen Formaten verfügbar (HTML, PDF, PostScript)
   1620 A4-Seiten PDF
   

   View Slide

5. Der aktuelle Stand
   Umfassende Dokumentation mit L
   AT
   EXgeschrieben
   In vielen Formaten verfügbar (HTML, PDF, PostScript)
   1620 A4-Seiten PDF (wobei L
   AT
   EXmit Papier groÿzügig
   umgeht)
   

   View Slide

6. Der aktuelle Stand
   Umfassende Dokumentation mit L
   AT
   EXgeschrieben
   In vielen Formaten verfügbar (HTML, PDF, PostScript)
   1620 A4-Seiten PDF (wobei L
   AT
   EXmit Papier groÿzügig
   umgeht)
   gröÿtenteils von Guido van Rossum und Fred L. Drake, Jr
   geschrieben
   

   View Slide

7. Der aktuelle Stand
   Umfassende Dokumentation mit L
   AT
   EXgeschrieben
   In vielen Formaten verfügbar (HTML, PDF, PostScript)
   1620 A4-Seiten PDF (wobei L
   AT
   EXmit Papier groÿzügig
   umgeht)
   gröÿtenteils von Guido van Rossum und Fred L. Drake, Jr
   geschrieben
   Documentation matters - einer der Gründe warum Python so
   populär ist.
   

   View Slide

8. Besonderheiten
   Gegenüber Ruby
   Umfassend (mit Tutorial, Referenz, Embedding-Anleitung,
   u.v.m.)
   Keine generierte API-Dokumentation
   

   View Slide

9. Besonderheiten
   Gegenüber Ruby
   Umfassend (mit Tutorial, Referenz, Embedding-Anleitung,
   u.v.m.)
   Keine generierte API-Dokumentation
   Englisch ;)
   Gegenüber Java
   Mitgeliefert
   In verschiedenen Formaten verfügbar
   Einfacher mitzuarbeiten
   

   View Slide

10. API-Dokumentation
    Es gibt auch javadoc-ähnliche Tools für Python
    pydoc, mitgeliefert
    Epydoc, kann mehr
    

    View Slide

11. API-Dokumentation
    Es gibt auch javadoc-ähnliche Tools für Python
    pydoc, mitgeliefert
    Epydoc, kann mehr (unter anderem reST)
    http://epydoc.sourceforge.net/stdlib/
    

    View Slide

12. Kritik
    Am Format
    L
    AT
    EXumständlich zu schreiben - wenig Interessenten
    Umständlich zu generieren - von Fred L. Drake angepasstes
    LaTeX2HTML
    keine Suchfunktion (nur über Google-Bot und pyhelp.cgi)
    http://starship.python.net/crew/theller/pyhelp.cgi
    Look von 1995
    Am Inhalt
    zu wenige Beispiele
    keine Möglichkeit für User-Kommentare wie in PHP
    

    View Slide

13. Kritik
    Am Format
    L
    AT
    EXumständlich zu schreiben - wenig Interessenten
    Umständlich zu generieren - von Fred L. Drake angepasstes
    LaTeX2HTML
    keine Suchfunktion (nur über Google-Bot und pyhelp.cgi)
    http://starship.python.net/crew/theller/pyhelp.cgi
    Look von 1995
    Am Inhalt
    zu wenige Beispiele
    keine Möglichkeit für User-Kommentare wie in PHP (also nicht
    Web 2.0-kompatibel)
    Schlecht verknüpft, Dinge schwer aufzunden
    

    View Slide

14. reST als Konkurrent zu L
    AT
    EX
    Was ist das?
    reStructured Text, ein Yet Another Markup-Format
    Konkurrenz zu Markdown, Textile und wie sie alle heiÿen
    Als Bestandteil der docutils entstanden
    Code-Beispiel
    Code here (highlighted by Pygments)
    

    View Slide

15. Was bringt das nun?
    Say something here
    

    View Slide