Sphinx Introduction

A quick overview over Sphinx I gave in January 2012 for the Python Users Berlin.

Transcript

1. robertlehmann.de Python Users Berlin 2012, Jan 19
3. \documentclass{manual}\usepackage[T1]{fontenc}\usepackage{textcomp}\ title{PythonTutorial}\input{boilerplate}\makeindex\begin{document}\make title\ifhtml\chapter*{FrontMatter\label{front}}\fi\input{copyright}\begin{a bstract}\noindent For a description of standard objects and modules, see the \citetitle[../lib/lib.html]{Python Library Reference} document. The \citetitle[../ref/ref.html]{Python Reference Manual} gives a more forma definition of the language. To write extensions in C or \Cpp, read \citetitle[../ext/ext.html]{Extending and Embedding the Python Interpreter and \citetitle[../api/api.html]{Python/C API Reference}. There are also several books covering Python in depth. \end{abstract} \tableofcontent \chapter{Whetting Your Appetite \label{intro}} Python enables programs to be written compactly and readably. Programs written in Python are typically much shorter than equivalent C, \Cpp{}, or Java programs, fo several reasons:\begin{itemize}\item the high-level data types allow you to express complex operations in a single statement;\item statement grouping is done by indentation;\item no variable or argument declarations are necessary.\end{itemize} On Windows machines, the Python installation i usually placed in \file{C:\e Python24}, though you can change this when you're running the installer: \begin{verbatim} set path=%path% C:\python24\end{verbatim}\begin{seealso}\seetitle[../lib/typesseq.html]{S equence Types}%{Strings, and the Unicode strings described in the nex section, are examples of \emph{sequence types}, and support the common operations supported by such types.}\end{seealso}\subsection{Unicode Strings \label{unicodeStrings}}\sectionauthor{Marc-Andre Lemburg}{mal@ lemburg.com}\begin{methoddesc}[list]{pop}{\optional{i}}If no index i specified, \code{a.pop()} removes and returns the last item in the list. You will see this notation frequently in the \citetitle[../lib/lib.html]{Python Everbody hates it with a passion.
4. Georg Brandl Python Core Developer © Andreas Schreiber, http://www.flickr.com/photos/onyame/6213664903/
5. wait, wait! or Pydoc or Doxygen Epydoc!? or ...
6. tutorial.rst "reST" is **ONE** word, *not two!* ... An Interlude on Docutils
7. Inline Markup *italics* italics **bold** bold ``code`` code `link <URL>`_ link :pep:`287` PEP 287 An Interlude on reStructuredText
8. Lists An Interlude on reStructuredText * Red Leicester * Cheshire * Brie • Red Leicester o Cheshire • Brie (1) Flying Circus 2) Holy Grail #. Life of Brian 1. Flying Circus 2. Holy Grail 3. Life of Brian Spanish Inquisition Nobody expects it. Spanish Inquisition Nobody expects it. :Name: Spamalot :Lyrics: Eric Idle Name: Spamalot Lyrics: Eric Idle
9. Lists An Interlude on reStructuredText * Red Leicester * Cheshire * Brie • Red Leicester o Cheshire • Brie (1) Flying Circus 2) Holy Grail #. Life of Brian 1. Flying Circus 2. Holy Grail 3. Life of Brian Spanish Inquisition Nobody expects it. Spanish Inquisition Nobody expects it. :Name: Spamalot :Lyrics: Eric Idle Name: Spamalot Lyrics: Eric Idle
10. Directives An Interlude on reStructuredText .. note:: Drink your milk. .. image:: kitty.png :align: right Powered by `Docutils`_. .. _Docutils: Powered by Docutils. .. Remove that cat! <!-- Remove that cat! --> http://icanhascheezburger.com/2007/07/30/nobody-expects-spanish-inquizishun/ Note Drink your milk. http://docutils.sf.net
11. Tables An Interlude on reStructuredText docutils.sourceforge.net Doctests PEP 267 Footnotes Code Sections Math Citations Command Line Options a fairly elaborate feature set, yet more readable "in the raw“ than HTML Admonitions Readable Unobtrusive Unambiguous Unsurprising Intuitive Easy Scalable Powerful Language-Neutral Extensible Output-format-neutral
12. tutorial.rst "reST" is **ONE** word, *not two!* ... An Interlude on Docutils
13. tutorial.rst "reST" is **ONE** word, *not two!* ... root para graph “reST” is strong emph ONE word, not two! para graph An Interlude on Docutils
14. tutorial.rst "reST" is **ONE** word, *not two!* ... root para graph “reST” is strong emph ONE word, not two! para graph tutorial “reST” is ONE word, not two! An Interlude on Docutils
15. tutorial.rst "reST" is **ONE** word, *not two!* ... root para graph “reST” is bold italics ONE word, not two! para graph tutorial "reST" is ONE word, not two! An Interlude on Docutils not capable of document hierarchies too generic 
17. implemented June 2007 as py-rest-doc live August 2007 on docs.python.org released March 2008 as Sphinx 1.0 in July 2010 terminating 0.6.x 1.1 in October 2011 at PyCon DE (LT#2) 1.1.2 in November 2011 latest stable release
18. Who’s using it All logos and trademarks are © Copyright their respective owners.
19. Who’s using it All logos and trademarks are © Copyright their respective owners. also: Doug Hellmann’s blog
20. Who’s using it All logos and trademarks are © Copyright their respective owners. also: Doug Hellmann’s blog and the Japanese
21. $ sphinx-quickstart Welcome to the Sphinx 1.1.2 quickstart utility. > Root path for the documentation [.]:
22. $ sphinx-quickstart Welcome to the Sphinx 1.1.2 quickstart utility. > Root path for the documentation [.]: PUB-2012-01 > Project name: > Author name(s): Python Users Berlin > Project version: 1.0
23. $ sphinx-quickstart Welcome to the Sphinx 1.1.2 quickstart utility. > Root path for the documentation [.]: PUB-2012-01 > Project name: > Author name(s): Python Users Berlin > Project version: 1.0 Please indicate if you want to use one of the following Sphinx extensions. > autodoc: automatically insert docstrings from modules (y/N) [n]:
24. $ sphinx-quickstart Welcome to the Sphinx 1.1.2 quickstart utility. > Root path for the documentation [.]: PUB-2012-01 > Project name: > Author name(s): Python Users Berlin > Project version: 1.0 Please indicate if you want to use one of the following Sphinx extensions. > autodoc: automatically insert docstrings from modules (y/N) [n]: ridiculously snipped
30. index.rst .. toctree:: tutorial reference/index faq
31. index.rst .. toctree:: tutorial reference/index faq tutorial.rst Python is an easy to lea powerful programming lan reference/index.rst .. toctree:: datamodel grammar thon?
32. index.rst .. toctree:: tutorial reference/index faq tutorial.rst Python is an easy to lea powerful programming lan reference/index.rst .. toctree:: datamodel grammar thon?
33. index.rst .. toctree:: tutorial reference/index faq tutorial.rst Python is an easy to lea powerful programming lan reference/index.rst .. toctree:: datamodel grammar thon? reference/datamodel.rst Objects are Python's abstraction for data. reference/grammar.rst This is the full Python grammar.
34. index.rst .. toctree:: tutorial reference/index faq tutorial.rst Python is an easy to lea powerful programming lan reference/index.rst .. toctree:: datamodel grammar thon? reference/datamodel.rst Objects are Python's abstraction for data. reference/grammar.rst This is the full Python grammar. feel lazy? globbing! .. toctree:: reference/* *
35. index.rst .. toctree:: tutorial reference/index faq tutorial.rst Python is an easy to learn, powerful programming language. reference/index.rst .. toctree:: datamodel grammar faq.rst What is Python? reference/datamodel.rst Objects are Python's abstraction for data. reference/grammar.rst This is the full Python grammar. feel lazy? globbing! .. toctree:: reference/* *
36. index.rst .. toctree:: tutorial reference/index faq tutorial.rst Python is an easy to learn, powerful programming language. reference/index.rst .. toctree:: datamodel grammar faq.rst What is Python? reference/datamodel.rst Objects are Python's abstraction for data. reference/grammar.rst This is the full Python grammar. feel lazy? globbing! .. toctree:: reference/* * ?
37. contents.rst .. class:: simplestmodule.Person Represent a person.
38. contents.rst .. class:: simplestmodule.Person Represent a person.
39. contents.rst .. class:: simplestmodule.Person Represent a person. or explicitly through index directive
40. index.rst .. autoclass:: simplestmodule.Person
41. index.rst .. autoclass:: simplestmodule.Person simplestmodule.py class Person(object): """Represents a person."""
42. index.rst .. autoclass:: simplestmodule.Person simplestmodule.py class Person(object): """Represents a person."""
43. index.rst .. autoclass:: simplestmodule.Person simplestmodule.py class Person(object): """Represents a person."""
44. index.rst .. autoclass:: simplestmodule.Person simplestmodule.py class Person(object): """Represents a person."""
45. http://alltheragefaces.com/face/misc-all-the-things Python • Modules • Data • Exceptions • Functions • Classes • Attributes • Methods • Static Methods • Class Methods • Decorators
46. http://alltheragefaces.com/face/misc-all-the-things Python • Modules • Data • Exceptions • Functions • Classes • Attributes • Methods • Static Methods • Class Methods • Decorators C • Functions • Members • Macros • Types • Variables • Standard • C++ • Javascript • reST • Ruby • Erlang • Ada • Http
47. tutorial.rst "reST" is **ONE** word, *not two!* ... tutorial.pdf tutorial.html tutorial.tex tutorial.1.gz tutorial.epub index.html tutorial.txt tutorial.json ChangeLog tutorial.qhp tutorial.devhelp
48. http://www.flickr.com/photos/cknara/5502182248/ 40+ third-party plugins epydoc, Doxygen, diagrams, spellchecker, hyphenation
49. Sphinx-PYPI-upload I CAN HAZ HOSTING?
50. • Lightning fast! • SVN, Mercurial, Git, Bazaar • Webhooks • HTML + PDF + Epub • Search • no conf.py • C dependencies I CAN HAZ HOSTING?
55. grab a coffee et voilà (celery in action)
56. et voilà
57. for 1.1 shameless plug
58. skip i18n dfa.c - deterministic extended regexp routines for GNU 2954 char *lcopy = malloc(len); 2955 if (!lcopy) 2956 dfaerror("out of memory"); 2954 char *lcopy = malloc(len); 2955 if (!lcopy) 2956 dfaerror(_("out of memory")); ftp://mirrors.kernel.org/gnu/grep/grep-2.5.1.tar.bz2 An Interlude on Internationalization
59. #: src/dfa.c:2956 msgid "out of memory" msgstr "" 2954 char *lcopy = malloc(len); 2955 if (!lcopy) 2956 dfaerror(_("out of memory")); grep.pot dfa.c An Interlude on Internationalization
60. http://translationproject.org/PO-files/de/grep-2.5.de.po #: src/dfa.c:2956 msgid "out of memory" msgstr "" "Speicher ist alle." msginit grep.po An Interlude on Internationalization
61. grep.mo #: src/dfa.c:2956 msgid "out of memory" msgstr "Speicher ist alle." grep.po An Interlude on Internationalization
62. 1346 #if defined(ENABLE_NLS) 1347 bindtextdomain("grep", "/usr/share/locale") 1348 textdomain("grep"); 1349 #endif grep.mo grep.c /usr/share/locale/de/LC_MESSAGES/grep.mo An Interlude on Internationalization
63. http://sphinx.pocoo.org/latest/intl.html replaces libintl.h replaces xgettext
64. http://sphinx.pocoo.org/ thanks.
65. Initializing Reading Resolving Writing Finishing Hooks Directives Sphinx Plugins