Created by Timmie on 2009-07-21 and last modified on 2009-07-21

Proposal for a common documentation workflow


OSGEO intends to create a common repository for the mutual creation and edition of
documentation, tutorials and teaching materials.
A common format can facilitate the collaborative editing as a format and editing system known
to all editors and usable by everyone regardsles of the operation system, preferred editor or
workflow has the following advantages:

* lower the entrance barrier for possible contributors
* reduce the number of formatting errors
* automise the buil and creation of final documents

A simple format: Restructured Text (ReST)

Restructured Text is a markup format mainly used in the documentation of software and
especially adopted as standard for Python docstrings.

* simple text format
* no styling
* widely adopted in the open-source programming world
* converter into various export formats (latex, html, odf) exist
    * `pandoc <http://sophos.berkeley.edu/macfarlane/pandoc/>`_
    * native: rst2html, rst2s5, rst2odp, rst2latex
    * additional: rst2beamer, rst2odt, rst2pdf
* easy to create screen presentations from the documents
* easy to import or include in academic publications through LaTex/LyX

* `Emacs: see docutils page <http://docutils.sourceforge.net/docs/user/emacs.html>`_

* `Gedit (Linux) <http://textmethod.com/wiki/ReStructuredTextToolsForGedit>`_

* `Ulipad (Win) <http://code.google.com/p/ulipad>`_

Alternative Formats
* Lyx which also support export to
    * PDF
    * HTML
    * ODT

A versatile build system: Sphinx

The documentation creation and build system `Sphinx <http://sphinx.pocoo.org/>`_ relys
on ReST as input format and uses its simple structure together with the `docutils <http://docutils.sourceforge.net/>`_
conversion utilities to offer a flexible documentation system.

It is used to prepare the documentation of one of the major scripting languages: `Python <http://www.python.org/>`_.
More and more `software projects <http://sphinx.pocoo.org/examples.html>`_ have adopted it
for their documentation; and while most of them are using Python, other programming
languages are also supported.


* as being the documentation tool for Python, contious development is ensured
* well documented
* a supportive user mailing list
* a `simple webinterface <http://code.google.com/p/pydocweb/>`_ for online editing available
  and a more advanced is
  `in development <http://gminick.wordpress.com>`_ under the current Summer of Code 2009
* editing is simple and accessible as ReST is used (see above)
* content is mostely separated from layout and styling
* theming support for layout and styling
* configurable content depending on output format
* supports markup suited for documentaion and software tutorials such as
    * equations
    * code highlighting
* literature citations are cared for and rudimentary bibtex plugin exists
* by consisting only of text files it is easy to include into a version control system
* the final documentation can be built into html or PDF among others
* can be build automatically with python distutils or any other build system

* An example of a community written book using Sphinx: Python3 Patterns
    * http://www.mindviewinc.com/Books/Python3Patterns/Index.php
    * http://www.artima.com/weblogs/viewpost.jsp?thread=239183
    * It is maintained in a DVCS: http://bitbucket.org/BruceEckel/python-3-patterns-idioms/

Get this branch:
bzr branch lp:~timmie/+junk/osgeo-edu_sphinxexample
Only Timmie can upload to this branch. If you are Timmie please log in for upload directions.

Related bugs

Related blueprints

Branch information


Recent revisions

1. By Timmie on 2009-07-21

created bazaar repo
initial commit

Branch metadata

Branch format:
Branch format 6
Repository format:
Bazaar pack repository format 1 (needs bzr 0.92)
This branch contains Public information 
Everyone can see this information.