Docutils Project Documentation Overview

Project Fundamentals

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

README:

Project overview: quick-start, requirements, installation, and usage.

COPYING:

Conditions for Docutils redistribution, with links to licenses.

FAQ:

Docutils Frequently Asked Questions. If you have a question or issue, there's a good chance it's already answered here.

BUGS:

A list of known bugs, and how to report a bug.

RELEASE-NOTES:

Summary of the major changes in recent releases and notice of future incompatible changes.

HISTORY:

Detailed change history log.

THANKS:

Acknowledgements.

Introductory & Tutorial Material for End-Users

Docutils-general:

• Docutils Front-End Tools

• Docutils Configuration

• Docutils Mailing Lists

• Docutils Link List

Writer-specific:

• Docutils HTML Writers

• Easy Slide Shows With reStructuredText & S5

• Docutils LaTeX Writer

• Man Page Writer for Docutils

• Docutils ODF/OpenOffice/odt Writer

reStructuredText:

• A ReStructuredText Primer (see also the text source)

• Quick reStructuredText (user reference)

• reStructuredText Cheat Sheet (text only; 1 page for syntax, 1 page directive & role reference)

• Demonstration of most reStructuredText features (see also the text source)

Editor support:

• Emacs support for reStructuredText

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 Generic DTD

• OASIS XML Exchange Table Model Declaration Module (CALS tables DTD module)

• Docutils Design Specification (PEP 258)

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

• LaTeX syntax for mathematics (syntax used in "math" directive and role)

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 developed independent from the local versions after submission.

Prehistoric:

Setext Documents Mirror

API Reference Material for Client-Developers

The Docutils Publisher

entry points for using Docutils as a library

Docutils Runtime Settings

configuration framework details

Docutils Transforms

change the document tree in-place (resolve references, …)

The Docutils Design Specification (PEP 258) is a must-read for any Docutils developer.

Instructions for Developers

Security:

Deploying Docutils Securely

• Inside A Docutils Command-Line Front-End Tool

• Runtime Settings Processing

• Writing HTML (CSS) Stylesheets for Docutils

• Docutils Internationalization

• Creating reStructuredText Directives

• Creating reStructuredText Interpreted Text Roles

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

• Plan for Enthought API Documentation Tool

• Enthought API Documentation Tool RFP

reStructuredText:

• A Record of reStructuredText Syntax Alternatives

• Problems With StructuredText