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.

user/: Introductory & Tutorial Material for End-Users

Docutils-general:

• Docutils Front-End Tools
• Docutils Configuration Files
• Docutils Mailing Lists
• Docutils Link List

Writer-specific:

• Easy Slide Shows With reStructuredText & S5
• Docutils LaTeX Writer

reStructuredText:

• A ReStructuredText Primer (HTML) (or text source)
• Quick reStructuredText (user reference)
• reStructuredText Cheat Sheet (text only; 1 page for syntax, 1 page directive & role reference)
• reStructuredText Demonstration (a demonstration of most reStructuredText features; you can also have a look at the text source)

Editor support:

• Emacs support for reStructuredText

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:

• The Docutils Document Tree (incomplete)
• Docutils Transforms
• Docutils Generic DTD
• OASIS XML Exchange Table Model Declaration Module (CALS tables DTD module)

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

reStructuredText:

• An Introduction to reStructuredText (includes the Goals and History of reStructuredText)
• reStructuredText Markup Specification
• reStructuredText Directives
• reStructuredText Interpreted Text Roles
• reStructuredText Standard Definition Files

Prehistoric:

• Setext Documents Mirror

peps/: Python Enhancement Proposals

• PEP 256: Docstring Processing System Framework is a high-level generic proposal. [PEP 256 in the master repository]
• PEP 257: Docstring Conventions addresses docstring style and touches on content. [PEP 257 in the master repository]
• PEP 258: Docutils Design Specification is an overview of the architecture of Docutils. It documents design issues and implementation details. [PEP 258 in the master repository]
• PEP 287: reStructuredText Docstring Format proposes a standard markup syntax. [PEP 287 in the master repository]

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

api/: API Reference Material for Client-Developers

• The Docutils Publisher
• Inside A Docutils Command-Line Front-End Tool
• Docutils Runtime Settings
• (Docutils Transforms should be moved here)

PEP 258 is an overview of the architecture of Docutils.

howto/: Instructions for Developers

• Writing HTML (CSS) Stylesheets for Docutils
• Docutils Internationalization
• Creating reStructuredText Directives
• Creating reStructuredText Interpreted Text Roles

dev/: Development Notes and Plans for Core-Developers

Docutils-general:

• Docutils Hacker's Guide
• Docutils Distributor's Guide
• Docutils To Do List
• Docutils Project Policies
• Docutils Web Site
• Docutils Release Procedure
• The Docutils Subversion Repository
• Docutils Testing
• Docstring Semantics (incomplete)
• Python Source Reader (incomplete)
• Docutils Python DTD (experimental)
• Plan for Enthought API Documentation Tool
• Enthought API Documentation Tool RFP

reStructuredText:

• A Record of reStructuredText Syntax Alternatives
• Problems With StructuredText