Embed Size (px)
DESCRIPTION
Mit Hilfe von Sphinx lassen sich Softwareprojekte einfach und trotzdem visuell ansprechend dokumentieren.Ursprünglich zur Dokumentation der Programmiersprache Python geschrieben benutzen inzwischen auch viele andere Projekte Sphinx.Mit Hilfe einer einfachen Markup-Sprache werden Sphinx-Dokumente formatiert und in einer Baumstruktur abgelegt. Es werden diverse Ausgabeformate unterstützt: HTML, LaTeX (zur Erzeugung von PDF-Dateien), Manual Pages und Plain Text.Sphinx ist Open Source Software (BSD Lizenz).
Citation preview
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.
