Sphinx

Documentation in Action

Sphinx and Pyramid

Egypt.Giza.Sphinx.02.jpg

Sphinx and Pyramid @ same meeting :)

What are the odds ?

Writing Documentation

Sumerian_26th_c_Adab.jpg

Writing documentation is hard

Good documentation

Moses_dore.jpg

Writing good, usable & acceptable documentation is harder

Enter Sphinx

Solid Foundation

PileDriving.jpg

rst - Sections

sections.png 
Title
=====
Subtitle
--------
Titles are underlined
(or over- and underlined)
with a printing
nonalphanumeric 7-bit ASCII
character. Recommended
choices are
"``= - ` : ' " ~ ^ _ * + # < >``".

rst - Lists

bullets.png 
Bullet lists:

- This is item 1
- This is item 2

- Bullets are "-", "*" or "+".
  Continuing text must be aligned
  after the bullet and whitespace.

rst - Admonition

admonition.png 
.. note:: This is a note admonition.
   This is the second line

.. warning:: Don't do that

.. tip::
    Do that and good things will follow

rst - More

Complete reStructuredText reference at docutils web site

Sphinx - Quick start

$ pip install sphinx
$ mkdir docs
$ sphinx-quickstart docs
...
$ cd docs
$ make html

conf.py

TOC tree

.. toctree::
   :maxdepth: 2

   install
   quickstart
   guide
Custom directive, adds relations between the single
files and table of contents.

Labels

Use for cross referencing.

For more info see :ref:`coolproj`

.. _coolproj:

Cool Project
==============

Indexing

index.png 
.. index::
    single: Execution Example
    single: User Guide; Execution Example

Execution Example
====================

Python Domain

Python Domain Example

.. py:function:: format_exception(etype, value, tb[, limit=None])

   Format the exception with a traceback.

   :param etype: exception type
   :param value: exception value
   :param tb: traceback object
   :param limit: maximum number of stack frames to show
   :type limit: integer or None
   :rtype: list of strings


For more info see :py:func:`format_exception`

Rendered Example

pydomain.png

Built in domains

Contrib

More domains and extensions at the Sphinx Contrib. Partial list:

And many more (youtube, feed, google analytics etc.).

autodoc extension

Can Import modules and create documentation from docstrings.

.. automodule:: awesome
   :members:

.. autoclass:: AwesomeCls
   :members:
   :inherited-members:

readthedocs.org

readthedocs.png

Images Credits

Contact