.. This document is *not* meant to be a model for good
   reStructuredText usage.  It is full of external hyperlinks, and
   makes extensive use of anonymous hyperlink syntax, which is not
   easy to follow from the source text.  Please refer to the processed
   HTML instead: http://docutils.sourceforge.net/index.html

==========================================
 Docutils: Python Documentation Utilities
==========================================

:Date: $Date$

.. topic:: DOCUTILS PROJECT COORDINATOR LOOKING FOR WORK

   `The coordinator of the Docutils project, David Goodger, is looking
   for a job, contract work, or consulting work.  Does your company
   need an experienced Python programmer and sysadmin?  Know of
   anybody who does?  Please follow this link for more info.
   <http://starship.python.net/~goodger/cv/>`__
      
The purpose of the Docutils project is to create a set of tools for
processing plaintext documentation into useful formats, such as HTML,
XML, and TeX.  Several sources will be supported:

- Standalone files (implemented).
- Inline documentation from Python modules and packages, extracted
  with namespace context.
- `PEPs (Python Enhancement Proposals)`_ (implemented).
- And others as discovered.

.. contents::


Getting Started
===============

To get up & running quickly, see the Quick-Start_ section of the
README_ file.

.. _Quick-Start: README.html#quick-start


Feedback
========

To the developers of an open source project, feedback is a great
motivator and very welcome.  We're working on Docutils in our own way,
pushing it along a more-or-less linear path that makes sense to us,
but may not necessarily be useful to everyone else.  Community
feedback helps steer development in immediately useful directions.

In other words: if you tell us what you need, you may just get it!  If
you really need something, please consider contributing_ to Docutils
in some way.

Please post any feedback to the appropriate `mailing list`_, or `email
the project coordinator`__ directly.

.. _contributing: `Please Contribute!`_
__ mailto_


Project Status
==============

The Docutils project began with the merging of the reStructuredText__
parser and the `Python Docstring Processing System`__ projects.  The
merge has been completed, and those projects are now inactive.

__ http://structuredtext.sourceforge.net/
__ http://docstring.sourceforge.net/

Docutils currently consists of a reStructuredText_ parser, readers for
standalone files and PEPs_, and writers for HTML, Docutils-native
XML, plus pseudo-XML for testing purposes.  A PDF writer has been
started, and a Python source reader (docstring extraction with
context) is also under way.  There is a lot of design and
implementation work to do, which could greatly benefit from a joint
effort with existing projects.  The project `To Do list`_ is brimming
over with ideas.

This project should be considered highly experimental; we're learning
as we go.  APIs are subject to change at any time.

.. _PEPs: `PEPs (Python Enhancement Proposals)`_


Requirements
------------

- Python 2.2 or later [#]_ must already be installed to run the code
  and the test suite.  The latest release is recommended (currently
  2.2.2).  Python is available from http://www.python.org/.

- Docutils uses Greg Ward's Optik_ option processing package.  It is
  now included in the Docutils distribution.

.. [#] Python 2.1 may be used providing the compiler package is
   installed.  The compiler package can be found in the Tools/
   directory of Python's source distribution.

.. _Optik: http://optik.sourceforge.net/


Development Snapshots
---------------------

Development snapshots of the project files are available as .tgz
tarballs.  They are generated automatically from CVS, usually within
an hour of a change being checked in.  The snapshots should be used
with caution, as they may contain transient bugs or incompatibilities.

- `Snapshot of Docutils code, tests, documentation, and
  specifications`__
- `Snapshot of the Sandbox`__ (experimental, contributed code; see
  `The Sandbox`_ below for details)
- `Snapshot of DocFactory project files`__ (this is a subset of the
  Sandbox snapshot above; you don't need both)
- `Snapshot of web files`__ (the files that generate this web site)

__ http://docutils.sourceforge.net/docutils-snapshot.tgz
__ http://docutils.sourceforge.net/docutils-sandbox-snapshot.tgz
__ http://docutils.sourceforge.net/docfactory-snapshot.tgz
__ http://docutils.sourceforge.net/docutils-web-snapshot.tgz

`Anonymous CVS access`_ is available.  You can also `browse the CVS
repository`_ and read the latest README_, HISTORY_, and FAQ_ files.


Project Releases
----------------

Putting together an official "Release" of Docutils is a significant
effort, so it isn't done that often.  Please note that the
`development snapshots`_ above contain the latest versions of project
files, and are strongly recommended.

The `latest project release package`_ (Docutils 0.2, 2002-07-31) and
past project releases can be downloaded from the `project files
page`_.


.. _mailing list:

Mailing Lists
-------------

Users who have questions or need assistance with Docutils or
reStructuredText should first check the `Docutils FAQ`_.  If the
question or problem is not answered there, please `post a message`__
to the `Docutils-Users mailing list`__.

Developers can keep up to date and help out by joining the mailing
lists.

High-level discussions take place on the `Python Documentation Special
Interest Group (Doc-SIG) mailing list`__ (email to
Doc-SIG@python.org).

Two lists have been set up specifically for developers of the Docutils
project:

- Docutils-develop__, for implementation discussions
  (email to docutils-develop@lists.sourceforge.net).
- Docutils-checkins__, to monitor CVS checkin messages (automatically
  generated; normally read-only).

The Doc-SIG_ has greater exposure and is therefore a better forum for
general discussions (such as reStructuredText syntax or the high-level
Docutils project model), whereas the Docutils-specific lists are more
focused on the implementation.

.. _FAQ:
.. _Docutils FAQ: FAQ.html
__ mailto:docutils-users@lists.sourceforge.net
__ http://lists.sourceforge.net/lists/listinfo/docutils-users
__ http://mail.python.org/mailman/listinfo/doc-sig
__ http://lists.sourceforge.net/lists/listinfo/docutils-develop
__ http://lists.sourceforge.net/lists/listinfo/docutils-checkins


User Documentation
==================

The latest working documents may be accessed individually below, or
from the ``docs`` directory of the `development snapshots`_ above. 
They are also distributed with the `latest project release package`_,
but those may not be completely up to date.

- `A ReStructuredText Primer`__ (HTML file, or `text source`__)
- `Quick reStructuredText`__ (user reference)
- `Docutils Front-End Tools`__

Also see the `Docutils FAQ`_.

__ docs/rst/quickstart.html
__ docs/rst/quickstart.txt
__ docs/rst/quickref.html
__ docs/tools.html


Developer Documentation
=======================

Specification
-------------

PEPs (Python Enhancement Proposals)
```````````````````````````````````

- `PEP 287: reStructuredText Docstring Format`__ proposes a standard
  markup syntax.  [`PEP 287`__ in the `master repository`_]
- `PEP 257: Docstring Conventions`__ addresses docstring style and
  touches on content.  [`PEP 257`__ in the `master repository`_]
- `PEP 256: Docstring Processing System Framework`__ presents a
  high-level generic processing proposal.  [`PEP 256`__ in the `master
  repository`_]
- `PEP 258: Docutils Design Specification`__ documents design issues
  and implementation details for Docutils (this project), a specific
  docstring processing system.  [`PEP 258`__ in the `master
  repository`_]

Please note that PEPs in the `master repository`_ may not be current,
whereas the local versions are.

__ spec/pep-0287.html
__ http://www.python.org/peps/pep-0287.html
__ spec/pep-0257.html
__ http://www.python.org/peps/pep-0257.html
__ spec/pep-0256.html
__ http://www.python.org/peps/pep-0256.html
__ spec/pep-0258.html
__ http://www.python.org/peps/pep-0258.html


Docutils Internals
``````````````````

- Notes__ (includes the Docutils `To Do list`_ and `Project
  Policies`__)
- `The Docutils Document Tree`__ (incomplete)
- `Docutils Transforms`__
- `Docstring Semantics`__ (incomplete)
- `Docutils Generic DTD`__
- `OASIS XML Exchange Table Model Declaration Module`__ (CALS tables
  DTD module)
- `Python Source Reader`_ (incomplete)
- `Docutils Python DTD`_ (experimental)

__ spec/notes.html
__ spec/notes.html#project-policies
__ spec/doctree.html
__ spec/transforms.html
__ spec/semantics.html
__ spec/docutils.dtd
__ spec/soextblx.dtd
.. _Python Source Reader: spec/pysource.html
.. _Docutils Python DTD: spec/pysource.dtd


reStructuredText
````````````````

Please also see the `reStructuredText home page`__.

- `An Introduction to reStructuredText`__ (includes the Goals__ and
  History__ of reStructuredText)
- `reStructuredText Markup Specification`__
- `reStructuredText Directives`__
- `reStructuredText Interpreted Text Roles`__
- `A Record of reStructuredText Syntax Alternatives`__
- `Problems With StructuredText`__

__ rst.html
__ spec/rst/introduction.html
__ spec/rst/introduction.html#goals
__ spec/rst/introduction.html#history
__ spec/rst/reStructuredText.html
__ spec/rst/directives.html
__ spec/rst/interpreted.html
__ spec/rst/alternatives.html
__ spec/rst/problems.html


How-To's
--------

- `Docutils Internationalization`__
- `Creating reStructuredText Directives`__

__ spec/howto/i18n.html
__ spec/howto/rst-directives.html


The Sandbox
===========

The Sandbox__ is a place to play around, to try out and share ideas.
It's a part of the CVS repository but it isn't distributed as part of
Docutils releases (you can get a recent tarball from the `development
snapshots`_).  Each developer who wants to play in it should create
their own subdirectory (suggested name: SourceForge ID, or given name
+ family initial).

Please feel free to `visit the sandbox`__.

It's OK to make a mess in the Sandbox!  But please, play nice.

__
__ sandbox/


Sandbox Projects
----------------

Anyone is welcome to contribute to any of these projects.  Interested
developers are welcome to take on any projects which appear to be
dormant.  Please direct any email to
docutils-develop@lists.sourceforge.net.

* ZReST_, by Richard Jones, is a "ReStructuredText Document for Zope"
  application that is complete and ready to install.

* PySource_, by Tony Ibbs, is an experimental Python source Reader. 
  In some form, it will soon become part of core Docutils.  There is
  some related code in David Goodger's sandbox (pysource_reader_) and
  a `Python Source Reader`_ document.

* Docutils interface to PythonPoint_, also by Richard Jones, produces
  PDF presentations using ReportLabs.

* Engelbert Gruber has begun `LaTeX Writer`_ and `ReportLabs/PDF
  Writer`_ components.

* Oliver Rutherfurd has begun a `DocBook Writer`_ component and
  `HT2HTML integration`_ component.

* Gunnar Schwant's DocFactory_ is a wxPython GUI application for
  Docutils.

* Aahz has begun an `OpenOffice.org Writer`_.

* Ian Bicking is working on code for a Wiki_.

* Bill Bumgarner has written a `simple HTML writer`_ that doesn't rely
  on CSS (stylesheets).

.. _ZReST: sandbox/richard/ZReST/
.. _PySource: sandbox/tibs/pysource/
.. _pysource_reader: sandbox/davidg/pysource_reader/
.. _PythonPoint: sandbox/richard/pythonpoint/
.. _LaTeX Writer: sandbox/grubert/latex/
.. _ReportLabs/PDF Writer: sandbox/grubert/rlpdf/
.. _DocBook Writer: sandbox/oliverr/docbook/
.. _HT2HTML integration: sandbox/oliverr/ht/
.. _DocFactory: sandbox/gschwant/docfactory/doc/
.. _OpenOffice.org Writer: sandbox/aahz/OO/
.. _Wiki: sandbox/ianb/wiki/
.. _simple HTML writer: sandbox/bbum/DocArticle/


Please Contribute!
==================

Please help this project succeed by contributing.  We're looking for
all kinds of contributions: testing, ideas, code, bug reports,
administration, tasty snacks, computer equipment, and large sums of
money.  There's a `To Do list`_ full of interesting ideas awaiting a
champion.  If you're interested in participating in any way, please
`contact the project coordinator`__.

__ mailto_


Project Links
=============

- `Project Summary page`__: `released files`__, `bug reports`__,
  patches__, `mailing lists`__, and news__.
- `Docutils CVS repository`__
- Project coordinator and architect: `David Goodger`_
- Please direct discussions to the `Python Documentation Special
  Interest Group (Doc-SIG)`__: doc-sig@python.org.
- Powered by |Python|__
- Hosted by |SourceForge|__

  __ http://sourceforge.net/projects/docutils/
  __ `project files page`_
  __ http://sourceforge.net/tracker/?group_id=38414&atid=422030
  __ http://sourceforge.net/tracker/?group_id=38414&atid=422032
  __ http://sourceforge.net/mail/?group_id=38414
  __ http://sourceforge.net/news/?group_id=38414

  __ CVS_

  __ Doc-SIG_

  __ http://www.python.org/
  .. |Python| image:: PyBanner016.png
  .. :border: 0

  __ http://sourceforge.net/
  .. |SourceForge| image::
     http://sourceforge.net/sflogo.php?group_id=38414
     :alt: SourceForge Logo
  .. :border: 0

.. _project files page:
   http://sourceforge.net/project/showfiles.php?group_id=38414
.. _Anonymous CVS access: http://sourceforge.net/cvs/?group_id=38414
.. _CVS:
.. _browse the CVS repository:
   http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/docutils/
.. _To Do list: spec/notes.html#to-do
.. _README: README.html
.. _HISTORY: HISTORY.html
.. _master repository: http://www.python.org/peps/
.. _mailto:
.. _David Goodger: mailto:goodger@users.sourceforge.net
.. _Doc-SIG: http://www.python.org/sigs/doc-sig/

.. _latest project release package:
   http://prdownloads.sourceforge.net/docutils/docutils-0.2.tar.gz


..
   Local Variables:
   mode: indented-text
   indent-tabs-mode: nil
   sentence-end-double-space: t
   fill-column: 70
   End:
