Dokumentation von

Softwareprojekten mit
Sphinx
Markus Zapke-Gründemann
Chemnitzer Linux-Tage 2011
Überblick

Vorstellung Installation
Was ist Sphinx? Erste Schritte
Das Projekt HTML Themes
Projekte, die Sphinx Extensions
nutzen
Read the Docs
Markus Zapke-Gründemann

Softwareentwickler seit 2001

Softwareentwicklung mit Python, Django und Mercurial
Freier Softwareentwickler und Berater seit 2008
www.keimlink.de
Was ist Sphinx?

Dokumentationssystem
Verarbeitet reStructuredText
Ausgabeformate: HTML, PDF, LaTeX, epub, manpages
Open Source Software (BSD Lizenz)
http://sphinx.pocoo.org
Das Projekt

Autor und Maintainer: Georg Brandl

Python
Jinja2 (Templates)
Pygments (Syntax Highlighting)
Docutils (reStructuredText)
Projekte, die Sphinx nutzen
Blender
Django
Drizzle
Python
SQLAlchemy
Zope
Installation
$ pip install sphinx

oder

http://pypi.python.org/pypi/Sphinx
$ tar xzf Sphinx-1.0.7.tar.gz
$ python setup.py build
$ sudo python setup.py install
Erste Schritte

$ sphinx-quickstart
Erste Schritte
index.rst

.. toctree::
:maxdepth: 2

intro
tutorial
...
Erste Schritte
First Steps with Sphinx
=======================

Setting up the documentation sources

------------------------------------

The root directory of a documentation collection is called the :term:`source

directory`. This directory also contains the Sphinx configuration file
:file:`conf.py`, where you can configure all aspects of how Sphinx reads your
sources and builds your documentation. [#]_

Sphinx comes with a script called :program:`sphinx-quickstart` that sets up a

source directory and creates a default :file:`conf.py` with the most useful
configuration values from a few questions it asks you. Just run ::

$ sphinx-quickstart

and answer its questions. (Be sure to say yes to the "autodoc" extension.)

http://sphinx.pocoo.org/rest.html
Erste Schritte

$ make html
Erste Schritte
First Steps with Sphinx
Setting up the documentation sources
The root directory of a documentation collection is called the source directory. This directory also
contains the Sphinx configuration file conf.py, where you can configure all aspects of how Sphinx
reads your sources and builds your documentation. [1]
Sphinx comes with a script called sphinx-quickstart that sets up a source directory and creates a
default conf.py with the most useful configuration values from a few questions it asks you. Just run

$ sphinx-quickstart

and answer its questions. (Be sure to say yes to the “autodoc” extension.)
HTML Themes

html_theme = "default"
HTML Themes

html_theme = "nature"
Extensions
autodoc
doctest
intersphinx
graphviz
coverage
todo
Read the Docs

http://readthedocs.org
 Lizenz
Dieses Werk ist unter einem Creative Commons
Namensnennung-Weitergabe unter gleichen
Bedingungen 3.0 Unported Lizenzvertrag lizenziert.
Um die Lizenz anzusehen, gehen Sie bitte zu
http://creativecommons.org/licenses/by-sa/3.0/ oder
schicken Sie einen Brief an Creative Commons, 171
Second Street, Suite 300, San Francisco, California
94105, USA.