Introduction to Sphinx documentation generator¶

Who are you?¶

http://about.me/shimizukawa, @shimizukawa

Activity:
- Sphinx co-maintainer
- Sphinx-users.jp chairman
- PyCon JP 2011,2012 vice-chairman

[speech]

Hi everyone. Today I’ll talk about Sphinx documentation generator. Thank you for opportunity of this presentation. Before that, let me introduce myself.

My name is Takayuki Shimizukawa, I came from Japan. I joined the PyConTW last year, and it is my second time to come to Taiwan.

My activity in Sphinx, I am a Sphinx co-maintainer and a Sphinx-uses.jp chariman. And Python, I was a vice-chairman PyCon JP in last 2 years.

Books¶

Expert Python Programming (translation into Japanese)
Python Professional Programming (2 chapters)
- Python開発実戦

[speech]

Books.

I want to show you my books. There are 2 books so far, each books tell you about Python Programming.

The books mention to Sphinx and Documentations.
“Python Professional Programming” was already translated into ‘simple chineese charactors’ and will publish in June. (This is chneese version book name).

anyway.¶

The Sphinx¶

[speech]

The Sphinx. Today, I’ll talk about documentation generator that is called “Sphinx”.

Table of contents¶

Introduction
Demonstration
Case studies

[speech]

I will tell about Sphinx by three parts. Introduction, Demonstration and Case studies.

Table of contents¶

Introduction
- Introduces the Sphinx and reStructuredText.
- Sphinx extensions.
- Comparison with other documentation tools.
Demonstration
Case studies

[speech]

First, I’ll introduce “what is Sphinx” and “what is reStructuredText”. By the way, how many people already using Sphinx?

OK, please raise your hands for about “Do you know Sphinx?” Thank you.

And next, “Did you use Sphinx already?” Thanks.

What IS Sphinx?¶

[speech]

What is Sphinx?

Sphinx IS¶

Documentation generator.
Sphinx generate documentation from reStructuredText markup.
Extendable.

_images/sphinx-generate-several-formats.png

[speech]

Sphinx is a documentation generator. Sphinx generate documentation from reStructuredText markup.

In other words, Sphinx reads reST text file and outputs html, epub, pdf, or other several formats.
Sphinx is extendable, so you can also output in a different format, or read the file in a different format.

And reStructuredText(reST) IS¶

Markup language.
Written with plain text.
Similer to several wiki markups.
Extendable (important!)

There is markup sample:

reStructuredText_ (*reST*) is **markup** language.
:term:`role` and :term:`directive` is extendable.

.. _reStructuredText: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html

reStructuredText (reST) is markup language. role and directive is extendable.

[speech]

And reStructuredText reST is markup language.

It was written with plain text.
reST is similer to other wiki like markups but different from others, the reST syntax is extendable. It’s a important point.

This is a markup sample that contains LINK, EMPHASIS, STRONG and TERM role.

Sphinx extends reST syntax¶

Sphinx provides many useful reST directive and role.

code-block: Code highlight directive
doc, ref, term: Link to other pages roles and directives
math: Numerical formula directive
only: Conditional output directive.
automodule: Auto documenter from .py directive.
domains: Some domains directives and roles: C, C++, JavaScript, Python, reST.

[speech]

Sphinx provides many useful reST directive and role.

code-block for code highlighting.
doc, ref, term, these roles make link to other pages.
math role and directive render numerical formula.
only directive works as conditional output control.
automodule generate module reference document from .py file.
Some domains directives and roles: C, C++, JavaScript, Python, reST to easy to write class or function’s descriptions. I’ll do demonstration later.

Sphinx includes¶

Simple and beautiful html themes. Detail information is here: Builtin themes.

default

sphinxdoc

scrolls

agogo

traditional

nature

haiku

pyramid

[speech]

Sphinx includes simple and beautiful html themes. Each themes are called: default, sphinxdoc, scrolls, agogo, traditional, nature, haiku and pyramid.

Detail information is written at builtin themes page.

There are 3rd party themes¶

You can find 3rd-party Sphinx themes at PyPI or other sites. For example,

And presentation themes:

htmlslide

impressjs

[speech]

There are 3rd party themes. You can find 3rd-party Sphinx themes at PyPI or other sites. For example, bizstyle, dotted, basicstrap and sphinxjp.

And few presentation themes are also exist: s6, htmlslide, impressjs.

BTW, this presentation slide was also built by Sphinx with s6 theme.

What IS NOT Sphinx?¶

[speech]

So, I’ll also introduce Sphinx is not possible.

What IS NOT Sphinx?¶

Are there GUI frontend editor?
- NO.

Windows Notepad

[speech]

Sphinx did not have GUI frontend as like as Word. But you can choose any GUI editor to edit reST plain text.

What IS NOT Sphinx?¶

There is a way to import/export Word?
- NO..!
  
  Some rights reserved by motorpsykhos

[speech]

Sphinx did not have a way to import Word file. However, there is a experimental implementation to build Word docx file, but it is not stable.

What IS NOT Sphinx?¶

There is a way to export to PowerPoint?
- NO.....!!!
  
  Some rights reserved by el__vaquero

[speech]

3rd-party theme will support to make presentation slide by using Sphinx. But it is controlled by HTML, css and JavaScript. It is not easy to convert PowerPoint file format.

What IS NOT Sphinx?¶

Are there a way to export to Excel?
- What are you saying???
  
  Some rights reserved by extranoise

[speech]

In Japan, many many documentations has been made with Excel. It is not feasible I think because it is not easy to maintenance and not easy to recognize difference by changing.

I think Sphinx will never support to convert to Excel.

Conclusion: Sphinx IS¶

Documentation generator.
Read reST and write several file formats.
Extends reST syntax and provides many useful roles and directives.
Contains many beautiful HTML themes.
Extendable.
NOT include office file converter.

[speech]

(read slide.)

Next.¶

Table of contents¶

Introduction
- Introduces the Sphinx and reStructuredText.
- Sphinx extensions.
- Comparison with other documentation tools.
Demonstration
Case studies

Included official extensions¶

autodoc: Auto documenter for Python modules.
pngmath or jsmath: provides math directive and role.
intersphinx: Link other documents over internet.
graphviz: Draw graphics by using graphviz.
todo: List-up todo directives.
doctest: run doctesting for code snippets in the document.
coverage: provide “make coverage” feature to get documentation coverage.

[speech]

Several official extensions are included in the Sphinx that are maintained by sphinx comitters.

autodoc, math, intersphinx, graphviz, todo, ... For about some extensions, I’ll do demonstration later.

Many 3rd-party extensions¶

Contributed extensions:

blockdiag: Rendering some type of diagrams from plain-text like graphviz.
Domains: ada, coffee, erlan, http, php, ruby.
or else.

And other extensions:

Some type of html themes (bizstyle, s6, ...)
Some type of builders (textile, docx, ...)

[speech]

You can find several extensions contributed by users in the Sphinx Contrib repository like these:

And you can find some extensions in PyPI. For example, Some type of html themes like bizstyle or s6. and some type of builders like textile or docx.

Next.¶

Table of contents¶

Introduction
- Introduces the Sphinx and reStructuredText.
- Sphinx extensions.
- Comparison with other documentation tools.
Demonstration
Case studies

Compare with other tools¶

Word like office app
Wiki

Sphinx vs Office¶

VS	Sphinx	Office
Files	Many files/dirs	1 monolithic file
Format	Plain text	Binary file
GUI	No GUI frontend	Must use GUI
Begin	Need learning to write	Easy to use
Restructuring	Easy	Difficult
Versioning	With hg/git/..	By self
Match to	Work with program source	Others

[speech]

Honestly, Word have powerful features as versioning or parallel editiong or some other features. But I think these features are hid to casual users.

Sphinx vs Wiki¶

VS	Sphinx	Wiki
Structure	1 tree	Semi-lattice
Root and path	1 root and 1 path from start to end	No root and no order to read
Cross reference	exists	exists
Glossary	exists	exists
Index	exists	exists
Match to	Books, order to read is important	Dictionary

[speech]

Sphinx is suitable for the text like a book or a paper.

The particle size of Wiki pages are small, it is suitable for the dictionary that does not depend on the order in which they read.

Next.¶

Table of contents¶

Introduction
Demonstration
Case studies

Sphinx installation¶

Install from PyPI:

$ easy_install Sphinx
Searching for Sphinx
Reading http://pypi.python.org/simple/Sphinx/
Best match: Sphinx 1.2b1
...
Finished processing dependencies for Sphinx

Sphinx and other dependency packages are installed. Sphinx 1.2b1 is current newest version.

[speech]

Install from PyPI by using easy_install.

easy_install is defacto standard package installer. There are other installation methods: pip, buildout or invoke setup.py. In this case I used easy_install.

This command installed Sphinx and other dependency packages. Sphinx 1.2b1 is current newest version.

Sphinx quick start¶

Generate a scaffold by using sphinx-quickstart:

$ sphinx-quickstart sample
(many interactive questions)

Generated files are:

$ cd sample
$ ls -a
./          Makefile    _static/    conf.py*    make.bat*
../         _build/     _templates/ index.rst

Run make html to build html output:

$ make html

[speech]

sphinx-quickstart command generate Sphinx documentation scaffold. And then, you can use make html command to build html output soon.

Generated html files are in _build/html directory.

demo: Bullet list¶

Some text line.
Second line will joined to 1st line.

* item 1
* item 2

  * item 2-1
  * item 2-2

* item 3

Some text line. Second line will joined to 1st line.

item 1
item 2
- item 2-1
- item 2-2
item 3

Tip

You need blank line before and after nested items. And nested items need 2 spaces before *.

demo: Numbered list¶

1. item 1
2. item 2

   #. item 2-1
   #. item 2-2

3. item 3

item 1
item 2
1. item 2-1
2. item 2-2
item 3

Tip

#. rendering auto numbered list. but it is not human readable.

[speech]

“number plus dot” or “sharp plus dot” render numbered list.

demo: Code highlight¶

Use code-block directive to rendering code with highlighting.

.. code-block:: ruby

   class Foo
     def initialize(value)
       puts "value = #{value}"
     end
   end

class Foo
  def initialize(value)
    puts "value = #{value}"
  end
end

Note

This directive was provided by sphinx. The same feature is provided by docutils-0.9 as code directive.

demo: Link to other pages¶

Use toctree directive to build a tree structure.

.. toctree::
   :numbered:
   :maxdepth: 2

   spam
   egg

Note

This directive was provided by sphinx.

demo: Link to other pages¶

Link between pages by using glossary directive and term role:

.. glossary::

   Sphinx
      Sphinx is a docmentation generator.

   reStructuredText
      reST is markup language to make structured document.

These glossary terms are linked from other pages
by using `term` role like :term:`Sphinx`.

Sphinx: Sphinx is a docmentation generator.
reStructuredText: reST is markup language to make structured document.

These glossary terms are linked from other pages by using term role like Sphinx.

demo: Link to other pages¶

Link between pages by using doc role:

Link to another reST page with :doc:`subdir/index`.
`subdir/index` will be replaced with title of
that's document file.

Link to another reST page with Subdirectory Root Page. subdir/index will be replaced with title of that’s document file.

demo: Numerical formula¶

Use math directive to rendering numerical formula.

Pythagoras theorem is :math:`a^2 + b^2 = c^2`.

.. math:: (a + b)^2 = a^2 + 2ab + b^2

.. math::
   :nowrap:

   \begin{eqnarray}
      y    & = & ax^2 + bx + c \\
      f(x) & = & x^2 + 2xy + y^2
   \end{eqnarray}

Pythagoras theorem is $a^2 + b^2 = c^2$ .

$(a + b)^2 = a^2 + 2ab + b^2$

$\begin{eqnarray} y & = & ax^2 + bx + c \\ f(x) & = & x^2 + 2xy + y^2 \end{eqnarray}$

Note

This directive was provided by sphinx. Same name directive was provided by docutils-0.8 or later, but it is bit different.

demo: todo extension¶

Add sphinx.ext.todo extension in conf.py:

extensions = [
    'sphinx.ext.todo',
]
todo_include_todos = True

Then you can use todo directive:

.. todo:: write test for this function.

Todo

write test for this function.

demo: todo extension¶

... and todolist directive:

.. todolist::

Todo

write test for this function.

(The original entry is located in c:\project\sphinx-doc\pycontw2013-sphinx-introduction\index.rst, line 1095.)

demo: autodoc extension¶

Add sphinx.ext.autodoc extension in conf.py:

extensions = [
    'sphinx.ext.autodoc',
]

Then you can use automodule directive:

.. automodule:: person
   :members:

class person.Person(name)¶

Person

greeting()¶

Retval :	greeting message.

demo: Link over internet¶

Add sphinx.ext.intersphinx extension and intersphinx setting in conf.py:

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.intersphinx',  #<- added
]

intersphinx_mapping = {
   'py': ('http://docs.python.jp/2/', None),
}

Then your linking markups link remote pages:

This markup link to Python's official reference page:
:py:func:`urllib.urlopen` on the :mod:`urllib` page.

This markup link to Python’s official reference page: urllib.urlopen() on the urllib page.

[speech]

Linking to other published Sphinx document by using same syntax to link to internal pages.

demo: Domains¶

A domain is a collection of markup (directives and roles) to describe and link to objects belonging together.

.. py:function:: event.register(event_id, user_name)

   (description for this function here).

You can use :py:func:`event.register` to register.

event.register(event_id, user_name)¶: (description for this function here).

You can use event.register() to register.

:py:func:`event.register` is py domain’s func role that make lnik to the declaration line.
.. py:function:: event.register(event_id, user_name) is py domain’s function directive that make declaration of the function and create Sphinx’s index page entry.

[speech]

What is domain? A domain is a collection of markup (reStructuredText directives and roles) to describe and link to objects belonging together.

For example. In this case, :py:func:`event.register` is py domain’s

func role that make lnik to the declaration line.

.. py:function:: event.register(event_id, user_name) is py domain’s function directive that make declaration of the function and create Sphinx’s index page entry.

Sphinx contains several domains and sphinx-contrib contains more useful domains.

demo: Internationalization¶

Sphinx generate po files for internationalization(i18n). sphinx-intl also support your work.

$ easy_install sphinx-intl

Generate pot files and create specified po files.

$ make gettext
$ sphinx-intl update -p _build/locale -l zh_TW

And next, you need translate po files in locale/ sub dirs. When you did that, set language=’zh_TW’ in the conf.py to use translated po files.

$ sphinx-intl build
$ make html

Ok, you can get the translated HTML.

[speech]

Sphinx generate pot files for internationalization(i18n). sphinx-intl also support your work that is 3rd-party tool then you need install this by using easy_install.

Generate po files can be done with make getext command. And next, you need translate po files in locale/ sub dirs. When you did that, set language=’zh_TW’ in the conf.py to use translated po files.

sphinx-intl build compile po files into mo files. Finally you can get the translated html by make html.

demo: blockdiag extensions¶

Blockdiag extensions is 3rd party extension for sphinx. Install sphinxcontrib-blockdiag extension:

$ easy_install Pillow
$ easy_install sphinxcontrib-blockdiag
$ easy_install sphinxcontrib-seqdiag
$ easy_install sphinxcontrib-actdiag
$ easy_install sphinxcontrib-nwdiag

Note

Pillow is successor of PIL (Python Imaging Library) that support Python3 and 64bit binary distributions.

demo: blockdiag extension¶

Add sphinxcontrib.blockdiag extension in conf.py:

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.intersphinx',
    'sphinxcontrib.blockdiag',  #<- added
]

Then you can use blockdiag directive:

.. blockdiag::

   {
       A [label="ME"];
       A -> B [label="Open"];
       A -> C;

       O -> P -> C;
   }

None

demo: seqdiag extension¶

Add sphinxcontrib.seqdiag extension in conf.py:

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.intersphinx',
    'sphinxcontrib.blockdiag',
    'sphinxcontrib.seqdiag',  #<- added
]

Then you can use seqdiag directive:

.. seqdiag::

   {
       A  => B;
       A  -> B;
       A <-- B;

       A => C => D;
   }

None

Next.¶

Table of contents¶

Introduction
Demonstration
Case studies
- Sphinx official reference
- Blog

[speech]

At last, I’ll introduce few case studies.

Sphinx official reference¶

http://sphinx-doc.org/index.html

[speech]

Of course, Sphinx official reference is created by using Sphinx.

Sphinx official reference¶

Using sphinx.ext.autodoc.

_images/sphinx-doc-storagebackend-src.png

source

Storage Backends

[speech]

For instance, Sphinx API part for developers is describing reference of functions and classes that was generated by autodoc.

Sphinx Japanese reference¶

Using Internationalization and Transifex.

http://docs.sphinx-users.jp/

sphinx-intl also support your work.

[speech]

And internationalization. This Japanese translated reference page in the sphinx-users.jp was generated by Sphinx with Japanese translation catalog that was imported from Transifex.

Transifex will help you to translate in a team. And sphinx-intl also support your work.

Blog¶

http://tinkerer.me/

[speech]

Tinkerer is a blog tool made by using the Sphinx. You can be written your blog in reStructuredText format. In addition, you can use the rich Sphinx extensions.

Blog with Tinkerer¶

Create a new blog:

$ mkdir blog
$ cd blog
$ tinker -s

And setup blog title or else:

$ vi conf.py

And create a blog entry file and write in reST:

$ tinker -p "first post"
$ vi 2013/05/25/first_post.rst

Finally, build command generates HTML and RSS:

$ tinker -b

[speech]

Tinkerer provides original commands to manage your blog; create a new blog, create a blog entry, build html.

(read slide)

Tinkerer make it easier to write a blog.

That’s all¶

Questions?¶

Information¶

[speech]

I’d like to introduce PyCon APAC 2013 in this autumn and Sphinx users community in Japan.

PyCon APAC 2013 in Japan¶

Schedule:
- Conference: Sep, 14(Sat) 15(Sun)
- Sprint: Sep, 16(Mon)
Location:
- Tokyo Shinjuku, Japan
Registration:
- Start at middle of June, (maybe)

[speech]

We will hold 3-days Python event at September 14, 15, 16 in Tokyo Japan.

Registration of this event will start at middle of June.

Sphinx-users.jp¶

Managing http://sphinx-users.jp
- Full-translated reference : http://docs.sphinx-users.jp/
- Original tutorial contents
- Reverse dictionary
Holding events
- Sphinx & translation hack-a-thon
- SphinxCon JP

[speech]

Sphinx users community group in Japan that was called “spinx users jp”.

The group manage original site that contains full-translated reference, original tutorials and reverse dictionary.

Also we holding monthly event “Sphinx & translation hack-a-thon” and annual event named “SphinxCon JP”

SphinxCon JP in PyCon JP 2012¶

The first Sphinx event in the world!

[speech]

SphinxCon JP at last year was very exciting. I think it is the first Sphinx event in the world! About 70 people were gathered on this event. We would like to do something in PyCon APAC of this year too. Please join to PyCon APAC!

Navigation

Introduction to Sphinx documentation generator¶

Who are you?¶

Books¶

anyway.¶

The Sphinx¶

Table of contents¶

Table of contents¶

What IS Sphinx?¶

Sphinx IS¶

And reStructuredText(reST) IS¶

Sphinx extends reST syntax¶

Sphinx includes¶

There are 3rd party themes¶

What IS NOT Sphinx?¶

What IS NOT Sphinx?¶

What IS NOT Sphinx?¶

What IS NOT Sphinx?¶

What IS NOT Sphinx?¶

Conclusion: Sphinx IS¶

Next.¶

Table of contents¶

Included official extensions¶

Many 3rd-party extensions¶

Next.¶

Table of contents¶

Compare with other tools¶

Sphinx vs Office¶

Sphinx vs Wiki¶

Next.¶

Table of contents¶

Sphinx installation¶

Sphinx quick start¶

Demo menu¶

demo: Bullet list¶

demo: Numbered list¶

demo: Code highlight¶

demo: Link to other pages¶

demo: Link to other pages¶

demo: Link to other pages¶

demo: Numerical formula¶

demo: todo extension¶

demo: todo extension¶

demo: autodoc extension¶

demo: Link over internet¶

demo: Domains¶

demo: Internationalization¶

demo: blockdiag extensions¶

demo: blockdiag extension¶

demo: seqdiag extension¶

Next.¶

Table of contents¶

Sphinx official reference¶

Sphinx official reference¶

Sphinx Japanese reference¶

Blog¶

Blog with Tinkerer¶

That’s all¶

Questions?¶

Information¶

PyCon APAC 2013 in Japan¶

Sphinx-users.jp¶

SphinxCon JP in PyCon JP 2012¶

Thank You!¶

Navigation