Docutils Project Documentation Overview

Author: David Goodger
Contact: docutils-develop@lists.sourceforge.net
Date: 2012-01-03
Revision: 7302
Copyright: This document has been placed in the public domain.

The latest working documents may be accessed individually below, or from the docs directory of the Docutils distribution.

Contents

Docutils Stakeholders

Docutils stakeholders can be categorized in several groups:

  1. End-users: users of reStructuredText and the Docutils tools. Although some are developers (e.g. Python developers utilizing reStructuredText for docstrings in their source), many are not.
  2. Client-developers: developers using Docutils as a library, programmers developing with Docutils.
  3. Component-developers: those who implement application-specific components, directives, and/or roles, separately from Docutils.
  4. Core-developers: developers of the Docutils codebase and participants in the Docutils project community.
  5. Re-implementers: developers of alternate implementations of Docutils.

There's a lot of overlap between these groups. Most (perhaps all) core-developers, component-developers, client-developers, and re-implementers are also end-users. Core-developers are also client-developers, and may also be component-developers in other projects. Component-developers are also client-developers.

Project Fundamentals

These files are for all Docutils stakeholders. They are kept at the top level of the Docutils project directory.

README.txt:Project overview: quick-start, requirements, installation, and usage.
COPYING.txt:Conditions for Docutils redistribution, with links to licenses.
FAQ.txt:Docutils Frequently Asked Questions. If you have a question or issue, there's a good chance it's already answered here.
BUGS.txt:A list of known bugs, and how to report a bug.
RELEASE-NOTES.txt:
 Summary of the major changes in recent releases.
HISTORY.txt:Detailed change history log.
THANKS.txt:Acknowledgements.

user/: Introductory & Tutorial Material for End-Users

Docutils-general:

Writer-specific:

reStructuredText:

Editor support:

ref/: Reference Material for All Groups

Many of these files began as developer specifications, but now that they're mature and used by end-users and client-developers, they have become reference material. Successful specs evolve into refs.

Docutils-general:

Although not in the "ref" directory, PEP 258 is a must-read reference for any Docutils developer.

reStructuredText:

Prehistoric:

peps/: Python Enhancement Proposals

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

api/: API Reference Material for Client-Developers

PEP 258 is an overview of the architecture of Docutils.

howto/: Instructions for Developers

dev/: Development Notes and Plans for Core-Developers

Docutils-general:

reStructuredText: