Sphinx Introduction

1,298 views

Published on

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

Published in: Technology, Spiritual
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
1,298
On SlideShare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
33
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

Sphinx Introduction

  1. 1. robertlehmann.de Python Users Berlin 2012, Jan 19
  2. 2. documentclass{manual}usepackage[T1]{fontenc}usepackage{textcomp}title{PythonTutorial}input{boilerplate}makeindexbegin{document}maketitleifhtmlchapter*{FrontMatterlabel{front}}fiinput{copyright}begin{abstract}noindent For a description of standard objects and modules, seethe citetitle[../lib/lib.html]{Python Library Reference} document. Thecitetitle[../ref/ref.html]{Python Reference Manual} gives a more formadefinition of the language. To write extensions in C or Cpp, readcitetitle[../ext/ext.html]{Extending and Embedding the Python Interpreterand citetitle[../api/api.html]{Python/C API Reference}. There are alsoseveral books covering Python in depth. end{abstract} tableofcontentchapter{Whetting Your Appetite label{intro}} Python enables programs tobe written compactly and readably. Programs written in Python aretypically much shorter than equivalent C, Cpp{}, or Java programs, foseveral reasons:begin{itemize}item the high-level data types allow you toexpress complex operations in a single statement;item statement groupingis done by indentation;item no variable or argument declarations arenecessary.end{itemize} On Windows machines, the Python installation iusually placed in file{C:e Python24}, though you can change this when Everbody hates it with a passion.youre running the installer: begin{verbatim} set path=%path%C:python24end{verbatim}begin{seealso}seetitle[../lib/typesseq.html]{Sequence Types}%{Strings, and the Unicode strings described in the nexsection, are examples of emph{sequence types}, and support the commonoperations supported by such types.}end{seealso}subsection{UnicodeStrings label{unicodeStrings}}sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com}begin{methoddesc}[list]{pop}{optional{i}}If no index ispecified, code{a.pop()} removes and returns the last item in the list. Youwill see this notation frequently in the citetitle[../lib/lib.html]{Python
  3. 3. Python Core Developer Georg Brandl© Andreas Schreiber, http://www.flickr.com/photos/onyame/6213664903/
  4. 4. wait, wait! Epydoc!? or Doxygen or Pydoc or ...
  5. 5. An Interlude on Docutils tutorial.rst "reST" is **ONE** word, *not two!* ...
  6. 6. An Interlude on reStructuredText *italics* italics **bold** bold ``code`` code `link <URL>`_ link :pep:`287` PEP 287 Inline Markup
  7. 7. An Interlude on reStructuredText * Red Leicester • Red Leicester o Cheshire * Cheshire • Brie * Brie (1) Flying Circus 1. Flying Circus 2) Holy Grail 2. Holy Grail #. Life of Brian 3. Life of Brian Spanish Inquisition Spanish Inquisition Nobody expects it. Nobody expects it. :Name: Spamalot Name: Spamalot :Lyrics: Eric Idle Lyrics: Eric Idle Lists
  8. 8. An Interlude on reStructuredText * Red Leicester • Red Leicester o Cheshire * Cheshire • Brie * Brie (1) Flying Circus 1. Flying Circus 2) Holy Grail 2. Holy Grail #. Life of Brian 3. Life of Brian Spanish Inquisition Spanish Inquisition Nobody expects it. Nobody expects it. :Name: Spamalot Name: Spamalot :Lyrics: Eric Idle Lyrics: Eric Idle Lists
  9. 9. An Interlude on reStructuredText .. note:: Note Drink your milk. Drink your milk. .. image:: kitty.png :align: right Powered by `Docutils`_. Powered by Docutils. .. _Docutils: http://docutils.sf.net .. Remove that cat! <!-- Remove that cat! -->http://icanhascheezburger.com/2007/07/30/nobody-expects-spanish-inquizishun/ Directives
  10. 10. An Interlude on reStructuredText Output-format-neutral Readable Scalable Intuitive Extensible Language-Neutral Unobtrusive Unambiguous Powerful Easy Unsurprising Math docutils.sourceforge.net Citations Sections PEP 267 Footnotes Tables Doctests Command Line Options Admonitions Code a fairly elaborate feature set, yet more readable "in the raw“ than HTML
  11. 11. An Interlude on Docutils tutorial.rst "reST" is **ONE** word, *not two!* ...
  12. 12. An Interlude on Docutils root tutorial.rst para para graph graph "reST" is **ONE** word, *not two!* ... strong emph “reST” is word, ONE not two!
  13. 13. An Interlude on Docutils tutorial “reST” is ONE word, not two! root tutorial.rst para para graph graph "reST" is **ONE** word, *not two!* ... strong emph “reST” is word, ONE not two!
  14. 14. An Interlude on Docutils tutorial "reST" is ONE word, not two! root not capable of document hierarchies tutorial.rst "reST" is too generic para graph para graph  **ONE** word, *not two!* ... bold italics “reST” is word, ONE not two!
  15. 15. 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
  16. 16. Who’s using itAll logos and trademarks are © Copyright their respective owners.
  17. 17. Who’s using it also: Doug Hellmann’s blogAll logos and trademarks are © Copyright their respective owners.
  18. 18. Who’s using it also: Doug Hellmann’s blog and the JapaneseAll logos and trademarks are © Copyright their respective owners.
  19. 19. $ sphinx-quickstartWelcome to the Sphinx 1.1.2 quickstart utility.> Root path for the documentation [.]:
  20. 20. $ sphinx-quickstartWelcome to the Sphinx 1.1.2 quickstart utility.> Root path for the documentation [.]:> Project name: PUB-2012-01> Author name(s): Python Users Berlin> Project version: 1.0
  21. 21. $ sphinx-quickstartWelcome to the Sphinx 1.1.2 quickstart utility.> Root path for the documentation [.]:> Project name: PUB-2012-01> Author name(s): Python Users Berlin> Project version: 1.0Please indicate if you want to use one of thefollowing Sphinx extensions.> autodoc: automatically insert docstrings frommodules (y/N) [n]:
  22. 22. $ sphinx-quickstartWelcome to the Sphinx 1.1.2 quickstart utility.> Root path for the documentation [.]:> Project name: PUB-2012-01> Author name(s): Python Users Berlin> Project version: 1.0Please indicate if you want to use one of thefollowing Sphinx extensions.> autodoc: automatically insert docstrings frommodules (y/N) [n]:ridiculously snipped
  23. 23. index.rst.. toctree:: tutorial reference/index faq
  24. 24. index.rst .. toctree:: tutorial reference/index faq reference/index.rst .. toctree:: tutorial.rst datamodel Python is an easy to lea grammar powerful programming lanthon?
  25. 25. index.rst .. toctree:: tutorial reference/index faq reference/index.rst .. toctree:: tutorial.rst datamodel Python is an easy to lea grammar powerful programming lanthon?
  26. 26. index.rst .. toctree:: tutorial reference/index faq reference/index.rst .. toctree:: tutorial.rst datamodel Python is an easy to lea grammar powerful programming lanthon? reference/datamodel.rst reference/grammar.rst Objects are Pythons This is the full abstraction for data. Python grammar.
  27. 27. index.rst .. toctree:: tutorial reference/index faq reference/index.rst .. toctree:: tutorial.rst feel lazy? globbing! datamodel grammar Python is an easy to lea powerful programming lan .. toctree:: reference/* *thon? reference/datamodel.rst reference/grammar.rst Objects are Pythons This is the full abstraction for data. Python grammar.
  28. 28. index.rst .. toctree:: reference/index.rst faq.rst feel lazy? globbing! tutorial tutorial.rst .. toctree:: reference/index.. toctree:: What is Python? faq Python is an easy to learn, reference/* reference/datamodel.rst language. powerful programming reference/grammar.rst datamodel grammar * This is the full Objects are Pythons Python grammar. abstraction for data.
  29. 29. ? index.rst .. toctree:: reference/index.rst faq.rst feel lazy? globbing! tutorial tutorial.rst .. toctree:: reference/index.. toctree:: What is Python? faq Python is an easy to learn, reference/* reference/datamodel.rst language. powerful programming reference/grammar.rst datamodel grammar * This is the full Objects are Pythons Python grammar. abstraction for data.
  30. 30. contents.rst.. class:: simplestmodule.Person Represent a person.
  31. 31. contents.rst.. class:: simplestmodule.Person Represent a person.
  32. 32. contents.rst.. class:: simplestmodule.Person Represent a person. or explicitly through index directive
  33. 33. index.rst.. autoclass:: simplestmodule.Person
  34. 34. index.rst.. autoclass:: simplestmodule.Personsimplestmodule.pyclass Person(object): """Represents a person."""
  35. 35. index.rst.. autoclass:: simplestmodule.Personsimplestmodule.pyclass Person(object): """Represents a person."""
  36. 36. index.rst.. autoclass:: simplestmodule.Personsimplestmodule.pyclass Person(object): """Represents a person."""
  37. 37. index.rst.. autoclass:: simplestmodule.Personsimplestmodule.pyclass Person(object): """Represents a person."""
  38. 38. Python • Modules • Data • Exceptions • Functions • Classes • Attributes • Methods • Static Methods • Class Methods • Decoratorshttp://alltheragefaces.com/face/misc-all-the-things
  39. 39. Python C • Modules • Functions • Data • Members • Exceptions • Macros • Functions • Types • Classes • Variables • Attributes • Methods • Standard • Ruby • Static Methods • C++ • Erlang • Class Methods • Javascript • Ada • Decorators • reST • Httphttp://alltheragefaces.com/face/misc-all-the-things
  40. 40. tutorial.rst tutorial.pdf "reST" is **ONE** word, tutorial.tex *not two!* ... tutorial.epub tutorial.qhp tutorial.devhelp tutorial.1.gztutorial.html tutorial.txt index.html tutorial.json ChangeLog
  41. 41. 40+ third-party plugins epydoc, Doxygen, diagrams, spellchecker, hyphenationhttp://www.flickr.com/photos/cknara/5502182248/
  42. 42. I CAN HAZ HOSTING? Sphinx-PYPI-upload
  43. 43. I CAN HAZ HOSTING?• Lightning fast!• SVN, Mercurial, Git, Bazaar • Webhooks • HTML + PDF + Epub • Search • no conf.py • C dependencies
  44. 44. grab a coffee et voilà (celery in action)
  45. 45. et voilà
  46. 46. shamelessplugfor 1.1
  47. 47. An Interlude on Internationalization skip i18n 2954 char *lcopy = malloc(len); 2955 if (!lcopy) 2956 dfaerror("out ofof memory")); dfaerror(_("out memory"); dfa.c - deterministic extended regexp routines for GNUftp://mirrors.kernel.org/gnu/grep/grep-2.5.1.tar.bz2
  48. 48. An Interlude on Internationalization 2954 char *lcopy = malloc(len); 2955 if (!lcopy) 2956 dfaerror(_("out of memory")); dfa.c grep.pot #: src/dfa.c:2956 msgid "out of memory" msgstr ""
  49. 49. An Interlude on Internationalization grep.po #: src/dfa.c:2956 msgid "out of memory" msginit "Speicher ist alle." msgstr ""http://translationproject.org/PO-files/de/grep-2.5.de.po
  50. 50. An Interlude on Internationalization #: src/dfa.c:2956 msgid "out of memory" msgstr "Speicher ist alle." grep.po grep.mo
  51. 51. An Interlude on Internationalization /usr/share/locale/de/LC_MESSAGES/grep.mo grep.mo grep.c1346 #if defined(ENABLE_NLS)1347 bindtextdomain("grep", "/usr/share/locale")1348 textdomain("grep");1349 #endif
  52. 52. replaces xgettext replaces libintl.hhttp://sphinx.pocoo.org/latest/intl.html
  53. 53. thanks.http://sphinx.pocoo.org/
  54. 54. Sphinx Plugins Initializing Reading Resolving Writing Finishing Directives Hooks

×