# Docutils Project Documentation Overview

Author:

  David Goodger

Contact:
  docutils-develop@lists.sourceforge.net
Date:
  2025-12-14
Revision:
  10272
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.

## Docutils Stakeholders

can be categorized in several groups:
  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.

  Client-developers

  developers using Docutils as a library, programmers developing with Docutils.

  Component-developers

  those who implement application-specific components, directives, and/or roles, separately from Docutils.

  Core-developers

  contributors to the Docutils codebase and participants in the Docutils project community.

  Re-implementers

  developers of alternate implementations of Docutils.

There's a lot of overlap between these groups.

Most (perhaps all) developers 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:

  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

  - 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 of reStructuredText)

  - 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.

## Docutils Enhancement Proposals

- Enhancement Proposal Index

## Instructions for Developers

- 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 Project Policies

  - Docutils Testing

  - Docutils Hacker's Guide

  - Docutils To Do List

  - Docutils Version Repository

  - Docutils Web Site

  - Docutils Release Procedure

  - Docutils Distributor's Guide

reStructuredText:

  - A Record of reStructuredText Syntax Alternatives

  - Problems With StructuredText

Suspended projects and plans:

  - Docstring Semantics (incomplete)

  - Python Source Reader (incomplete)

  - Docutils Python DTD

  - Plan for Enthought API Documentation Tool

  - Enthought API Documentation Tool RFP