Sphinx

Dokumentation von Softwareprojekten mit SphinxMarkus Zapke-Gründemann

Chemnitzer Linux-Tage 2011

Überblick

Vorstellung

Was ist Sphinx?

Das Projekt

Projekte, die Sphinx nutzen

Installation

Erste Schritte

HTML Themes

Extensions

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 Schritteindex.rst

.. toctree:: :maxdepth: 2

intro tutorial ...

Erste SchritteFirst Steps with Sphinx=======================

Setting up the documentation sources------------------------------------

The root directory of a documentation collection is called the :term:`sourcedirectory`. This directory also contains the Sphinx configuration file:file:`conf.py`, where you can configure all aspects of how Sphinx reads yoursources and builds your documentation. [#]_

Sphinx comes with a script called :program:`sphinx-quickstart` that sets up asource directory and creates a default :file:`conf.py` with the most usefulconfiguration 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 SphinxSetting up the documentation sourcesThe 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.