Sphinx (Docutils) Project Documentation¶
The latest working documents may be accessed individually below, or
from the docs directory of the Docutils distribution.
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:
- Easy Slide Shows With reStructuredText & S5
- Docutils LaTeX Writer
- Docutils ODF/OpenOffice/odt Writer
- 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:
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.
- 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:
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.
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