Docutils Project Documentation Overview
- Contact:
- docutils-develop@lists.sourceforge.net
- Date:
- 2021-11-10
- Revision:
- 8883
- 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
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: developers of 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) 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:
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)
reStructuredText Demonstration (a demonstration of most reStructuredText features; you can also have a look at the text source)
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:
The Docutils Document Tree (incomplete)
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.
An Introduction to reStructuredText (includes the Goals and History of reStructuredText)
LaTeX syntax for mathematics (syntax used in "math" directive and role)
Prehistoric:
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
(Docutils Transforms should be moved here)
PEP 258 is an overview of the architecture of Docutils.
howto/: Instructions for Developers
dev/: Development Notes and Plans for Core-Developers
Docutils-general:
Docstring Semantics (incomplete)
Python Source Reader (incomplete)