sphinx introduction

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


* 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


.. note:: Drink your milk.

.. image:: kitty.png :align: right

Powered by `Docutils`_. .. _Docutils:

Powered by Docutils.

.. Remove that cat! 

http://icanhascheezburger.com/2007/07/30/nobody-expects-spanish-inquizishun/

Note Drink your milk.

http://docutils.sf.net

Tables


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



tutorial.rst


root

para graph

“reST” is

strong emph

ONE

word,

not two!

para graph


tutorial.rst


root

para graph

“reST” is

strong emph

ONE

word,

not two!

para graph

tutorial

“reST” is ONE word, not two!


tutorial.rst


root

para graph

“reST” is

bold italics

ONE

word,

not two!

para graph

tutorial

"reST" is ONE word, not two!


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.

http://www.amazon.co.jp/gp/product/images/4048689525/ref=dp_image_0?ie=UTF8&n=465392&s=books

Who’s using it


also: Doug Hellmann’s blog


Who’s using it


also: Doug Hellmann’s blog

and the Japanese


$ 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]:





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


tutorial.rst

Python is an easy to learn, powerful programming language.

reference/index.rst

.. toctree:: datamodel grammar

What is Python?

index.rst


tutorial.rst


reference/index.rst


What is Python?

reference/datamodel.rst

Objects are Python's abstraction for data.

reference/grammar.rst

This is the full Python grammar.

index.rst


tutorial.rst


reference/index.rst


What is Python?





feel lazy? globbing! .. toctree:: reference/* *

index.rst


tutorial.rst


reference/index.rst


faq.rst

What is Python?






index.rst


tutorial.rst


reference/index.rst


faq.rst

What is Python?






?

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."""

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


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


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


grep.mo

#: src/dfa.c:2956 msgid "out of memory" msgstr "Speicher ist alle."

grep.po


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


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

sphinx introduction

Technology