Docutils Project Documentation Overview (original) (raw)
David Goodger
Contact:
docutils-develop@lists.sourceforge.net
Date:
2025-04-22
Revision:
10101
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
- Project Fundamentals
- Introductory & Tutorial Material for End-Users
- Reference Material for All Groups
- API Reference Material for Client-Developers
- Docutils Enhancement Proposals
- Instructions for Developers
- Development Notes and Plans for Core-Developers
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.
Project overview: quick-start, requirements, installation, and usage.
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.
Summary of the major changes in recent releases and notice of future incompatible changes.
Detailed change history log.
Acknowledgements.
Introductory & Tutorial Material for End-Users
Docutils-general:
Writer-specific:
- Docutils HTML Writers
- Easy Slide Shows With reStructuredText & S5
- Docutils LaTeX Writer
- Man Page Writer for Docutils
- Docutils ODF/OpenOffice/odt Writer
- 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)
- Demonstrationof most reStructuredText features (see also the text source)
Editor support:
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)
- An Introduction to reStructuredText(includes the Goalsof 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:
API Reference Material for Client-Developers
entry points for using Docutils as a library
configuration framework details
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
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
Suspended projects and plans: