1 ==========================================
2 Docutils_ Project Documentation Overview
3 ==========================================
6 :Contact: goodger@python.org
9 :Copyright: This document has been placed in the public domain.
11 The latest working documents may be accessed individually below, or
12 from the ``docs`` directory of the `Docutils distribution`_.
14 .. _Docutils: http://docutils.sourceforge.net/
15 .. _Docutils distribution: http://docutils.sourceforge.net/#download
23 Docutils stakeholders can be categorized in several groups:
25 1. End-users: users of reStructuredText and the Docutils tools.
26 Although some are developers (e.g. Python developers utilizing
27 reStructuredText for docstrings in their source), many are not.
29 2. Client-developers: developers using Docutils as a library,
30 programmers developing *with* Docutils.
32 3. Component-developers: those who implement application-specific
33 components, directives, and/or roles, separately from Docutils.
35 4. Core-developers: developers of the Docutils codebase and
36 participants in the Docutils project community.
38 5. Re-implementers: developers of alternate implementations of
41 There's a lot of overlap between these groups. Most (perhaps all)
42 core-developers, component-developers, client-developers, and
43 re-implementers are also end-users. Core-developers are also
44 client-developers, and may also be component-developers in other
45 projects. Component-developers are also client-developers.
51 These files are for all Docutils stakeholders. They are kept at the
52 top level of the Docutils project directory.
54 :README.txt_: Project overview: quick-start, requirements,
55 installation, and usage.
56 :COPYING.txt_: Conditions for Docutils redistribution, with links to
58 :FAQ.txt_: Docutils Frequently Asked Questions. If you have a
59 question or issue, there's a good chance it's already
61 :BUGS.txt_: A list of known bugs, and how to report a bug.
62 :HISTORY.txt_: Change history log.
63 :THANKS.txt_: Acknowledgements.
65 .. _README.txt: ../README.html
66 .. _BUGS.txt: ../BUGS.html
67 .. _COPYING.txt: ../COPYING.html
69 .. _FAQ.txt: ../FAQ.html
70 .. _HISTORY.txt: ../HISTORY.html
71 .. _THANKS.txt: ../THANKS.html
76 ``user/``: Introductory & Tutorial Material for End-Users
77 =========================================================
81 * `Docutils Front-End Tools <user/tools.html>`__
82 * `Docutils Configuration Files <user/config.html>`__
83 * `Docutils LaTeX Writer <user/latex.html>`__
84 * `Docutils Mailing Lists <user/mailing-lists.html>`__
85 * `Docutils Link List <user/links.html>`__
87 `reStructuredText <http://docutils.sourceforge.net/rst.html>`_:
89 * `A ReStructuredText Primer (HTML) <user/rst/quickstart.html>`__ (or
90 `text source <user/rst/quickstart.txt>`__)
91 * `Quick reStructuredText <user/rst/quickref.html>`__ (user reference)
92 * `reStructuredText Cheat Sheet <user/rst/cheatsheet.txt>`__ (text
93 only; 1 page for syntax, 1 page directive & role reference)
94 * `reStructuredText Demonstration <user/rst/demo.html>`_ (a
95 demonstration of most reStructuredText features; you can also have a
96 look at the `text source <user/rst/demo.txt>`__)
100 * `Emacs support for reStructuredText <user/emacs.html>`_
105 ``ref/``: Reference Material for All Groups
106 ===========================================
108 Many of these files began as developer specifications, but now that
109 they're mature and used by end-users and client-developers, they have
110 become reference material. Successful specs evolve into refs.
114 * `The Docutils Document Tree <ref/doctree.html>`__ (incomplete)
115 * `Docutils Transforms <ref/transforms.html>`__
116 * `Docutils Generic DTD <ref/docutils.dtd>`__
117 * `OASIS XML Exchange Table Model Declaration Module
118 <ref/soextblx.dtd>`__ (CALS tables DTD module)
120 Although not in the "ref" directory, `PEP 258`_ is a must-read
121 reference for any Docutils developer.
125 * `An Introduction to reStructuredText <ref/rst/introduction.html>`__
126 (includes the `Goals <ref/rst/introduction.html#goals>`__ and
127 `History <ref/rst/introduction.html#history>`__ of reStructuredText)
128 * `reStructuredText Markup Specification <ref/rst/restructuredtext.html>`__
129 * `reStructuredText Directives <ref/rst/directives.html>`__
130 * `reStructuredText Interpreted Text Roles <ref/rst/roles.html>`__
131 * `reStructuredText Standard Substitution Definition Sets
132 <ref/rst/substitutions.html>`_
136 * `Setext Documents Mirror
137 <http://docutils.sourceforge.net/mirror/setext.html>`__
142 ``peps/``: Python Enhancement Proposals
143 =======================================
145 * `PEP 256: Docstring Processing System Framework`__ is a high-level
146 generic proposal. [`PEP 256`__ in the `master repository`_]
147 * `PEP 257: Docstring Conventions`__ addresses docstring style and
148 touches on content. [`PEP 257`__ in the `master repository`_]
149 * `PEP 258: Docutils Design Specification`__ is an overview of the
150 architecture of Docutils. It documents design issues and
151 implementation details. [`PEP 258`__ in the `master repository`_]
152 * `PEP 287: reStructuredText Docstring Format`__ proposes a standard
153 markup syntax. [`PEP 287`__ in the `master repository`_]
155 Please note that PEPs in the `master repository`_ may not be current,
156 whereas the local versions are.
158 __ peps/pep-0256.html
159 __ http://www.python.org/peps/pep-0256.html
160 __ peps/pep-0257.html
161 __ http://www.python.org/peps/pep-0257.html
163 __ peps/pep-0258.html
164 __ http://www.python.org/peps/pep-0258.html
165 __ peps/pep-0287.html
166 __ http://www.python.org/peps/pep-0287.html
167 .. _master repository: http://www.python.org/peps/
172 ``api/``: API Reference Material for Client-Developers
173 ======================================================
175 * `The Docutils Publisher <api/publisher.html>`__
176 * `Inside A Docutils Command-Line Front-End Tool <api/cmdline-tool.html>`__
177 * `Docutils Runtime Settings <api/runtime-settings.html>`__
178 * (`Docutils Transforms <ref/transforms.html>`__ should be moved here)
180 `PEP 258`_ is an overview of the architecture of Docutils.
185 ``howto/``: Instructions for Developers
186 =======================================
188 * `Writing HTML (CSS) Stylesheets for Docutils
189 <howto/html-stylesheets.html>`__
190 * `Docutils Internationalization <howto/i18n.html>`__
191 * `Creating reStructuredText Directives <howto/rst-directives.html>`__
192 * `Creating reStructuredText Interpreted Text Roles
193 <howto/rst-roles.html>`__
198 ``dev/``: Development Notes and Plans for Core-Developers
199 =========================================================
203 * `Docutils Hacker's Guide <dev/hacking.html>`__
204 * `Docutils Distributor's Guide <dev/distributing.html>`__
205 * `Docutils To Do List <dev/todo.html>`__
206 * `Docutils Project Policies <dev/policies.html>`__
207 * `Docutils Web Site <dev/website.html>`__
208 * `Docutils Release Procedure <dev/release.html>`__
209 * `The Docutils Subversion Repository <dev/repository.html>`__
210 * `Docutils Testing <dev/testing.html>`__
211 * `Docstring Semantics <dev/semantics.html>`__ (incomplete)
212 * `Python Source Reader <dev/pysource.html>`_ (incomplete)
213 * `Docutils Python DTD <dev/pysource.dtd>`_ (experimental)
214 * `Plan for Enthought API Documentation Tool <dev/enthought-plan.html>`_
215 * `Enthought API Documentation Tool RFP <dev/enthought-rfp.html>`_
219 * `A Record of reStructuredText Syntax Alternatives
220 <dev/rst/alternatives.html>`__
221 * `Problems With StructuredText <dev/rst/problems.html>`__
227 indent-tabs-mode: nil
228 sentence-end-double-space: t