sphinx introduction
DESCRIPTION
A quick overview over Sphinx I gave in January 2012 for the Python Users Berlin.TRANSCRIPT
robertlehmann.de Python Users Berlin
2012, Jan 19
\documentclass{manual}\usepackage[T1]{fontenc}\usepackage{textcomp}\title{PythonTutorial}\input{boilerplate}\makeindex\begin{document}\maketitle\ifhtml\chapter*{FrontMatter\label{front}}\fi\input{copyright}\begin{abstract}\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 formal 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} \tableofcontents \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, for 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 is 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]{Sequence Types}%{Strings, and the Unicode strings described in the next 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 is 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 Library Reference}.)\end{methoddesc}
Everbody hates it with a passion.
Georg Brandl Python Core Developer
© A
nd
reas Schreib
er, http
://ww
w.flickr.co
m/p
ho
tos/o
nyam
e/6213664903/
wait, wait!
or Pydoc or Doxygen Epydoc!?
or ...
tutorial.rst
"reST" is **ONE** word, *not two!* ...
An Interlude on Docutils
Inline Markup
*italics* italics
**bold** bold
``code`` code
`link <URL>̀ _ link
:pep:`287` PEP 287
An Interlude on reStructuredText
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
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
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
Tables
An Interlude on reStructuredText
docutils.sourceforge.net
Doctests PEP 267 Foo
tno
tes
Code
Sections
Math Citations
Command Line Options
a fairly elaborate feature set, yet more readable "in the raw“
than HTML
Admonitions
Readable U
no
btru
sive
Unambiguous
Unsurprising
Intuitive
Easy
Scalable Powerful
Language-Neutral
Extensib
le
Output-format-neutral
tutorial.rst
"reST" is **ONE** word, *not two!* ...
An Interlude on Docutils
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
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
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
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
Who’s using it
All logos and trademarks are © Copyright their respective owners.
Who’s using it
All logos and trademarks are © Copyright their respective owners.
also: Doug Hellmann’s blog
Who’s using it
All logos and trademarks are © Copyright their respective owners.
also: Doug Hellmann’s blog
and the Japanese
$ sphinx-quickstart Welcome to the Sphinx 1.1.2 quickstart utility. > Root path for the documentation [.]:
$ 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
$ 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]:
$ 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
index.rst
.. toctree:: tutorial reference/index faq
index.rst
.. toctree:: tutorial reference/index faq
tutorial.rst
Python is an easy to learn, powerful programming language.
reference/index.rst
.. toctree:: datamodel grammar
What is Python?
index.rst
.. toctree:: tutorial reference/index faq
tutorial.rst
Python is an easy to learn, powerful programming language.
reference/index.rst
.. toctree:: datamodel grammar
What is Python?
index.rst
.. toctree:: tutorial reference/index faq
tutorial.rst
Python is an easy to learn, powerful programming language.
reference/index.rst
.. toctree:: datamodel grammar
What is Python?
reference/datamodel.rst
Objects are Python's abstraction for data.
reference/grammar.rst
This is the full Python grammar.
index.rst
.. toctree:: tutorial reference/index faq
tutorial.rst
Python is an easy to learn, powerful programming language.
reference/index.rst
.. toctree:: datamodel grammar
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/* *
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/* *
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/* *
?
contents.rst
.. class:: simplestmodule.Person Represent a person.
contents.rst
.. class:: simplestmodule.Person Represent a person.
contents.rst
.. class:: simplestmodule.Person Represent a person.
or explicitly through index directive
index.rst
.. autoclass:: simplestmodule.Person
index.rst
.. autoclass:: simplestmodule.Person
simplestmodule.py
class Person(object): """Represents a person."""
index.rst
.. autoclass:: simplestmodule.Person
simplestmodule.py
class Person(object): """Represents a person."""
index.rst
.. autoclass:: simplestmodule.Person
simplestmodule.py
class Person(object): """Represents a person."""
index.rst
.. autoclass:: simplestmodule.Person
simplestmodule.py
class Person(object): """Represents a person."""
http://alltheragefaces.com/face/misc-all-the-things
Python • Modules • Data • Exceptions • Functions • Classes
• Attributes • Methods • Static Methods • Class Methods
• Decorators
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
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
http://www.flickr.com/photos/cknara/5502182248/
40+ third-party plugins epydoc, Doxygen, diagrams, spellchecker, hyphenation
Sphinx-PYPI-upload
I CAN HAZ HOSTING?
• Lightning fast! • SVN, Mercurial, Git, Bazaar
• Webhooks • HTML + PDF + Epub • Search • no conf.py • C dependencies
I CAN HAZ HOSTING?
grab a coffee et voilà
(celery in action)
et voilà
for 1.1 shameless plug
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
#: 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
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
grep.mo
#: src/dfa.c:2956 msgid "out of memory" msgstr "Speicher ist alle."
grep.po
An Interlude on Internationalization
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
http://sphinx.pocoo.org/latest/intl.html
replaces libintl.h
replaces xgettext
http://sphinx.pocoo.org/
thanks.
Initializing Reading Resolving Writing Finishing
Hooks Directives
Sphinx Plugins