1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
|
==========================================
Docutils_ Project Documentation Overview
==========================================
:Author: David Goodger
:Contact: docutils-develop@lists.sourceforge.net
:Date: $Date$
:Revision: $Revision$
: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: http://docutils.sourceforge.net/
.. _Docutils distribution: http://docutils.sourceforge.net/#download
.. contents::
Docutils Stakeholders
=====================
Docutils stakeholders can be categorized in several groups:
1. 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.
2. Client-developers: developers using Docutils as a library,
programmers developing *with* Docutils.
3. Component-developers: those who implement application-specific
components, directives, and/or roles, separately from Docutils.
4. Core-developers: developers of the Docutils codebase and
participants in the Docutils project community.
5. 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.
.. _README.txt: ../README.html
.. _BUGS.txt: ../BUGS.html
.. _COPYING.txt: ../COPYING.html
.. _Docutils FAQ:
.. _FAQ.txt: ../FAQ.html
.. _RELEASE-NOTES.txt: ../RELEASE-NOTES.html
.. _HISTORY.txt: ../HISTORY.html
.. _THANKS.txt: ../THANKS.html
.. _user:
``user/``: Introductory & Tutorial Material for End-Users
=========================================================
Docutils-general:
* `Docutils Front-End Tools <user/tools.html>`__
* `Docutils Configuration <user/config.html>`__
* `Docutils Mailing Lists <user/mailing-lists.html>`__
* `Docutils Link List <user/links.html>`__
Writer-specific:
* `Easy Slide Shows With reStructuredText & S5 <user/slide-shows.html>`__
* `Docutils LaTeX Writer <user/latex.html>`__
* `Docutils ODF/OpenOffice/odt Writer <user/odt.html>`__
`reStructuredText <http://docutils.sourceforge.net/rst.html>`_:
* `A ReStructuredText Primer (HTML) <user/rst/quickstart.html>`__ (or
`text source <user/rst/quickstart.txt>`__)
* `Quick reStructuredText <user/rst/quickref.html>`__ (user reference)
* `reStructuredText Cheat Sheet <user/rst/cheatsheet.txt>`__ (text
only; 1 page for syntax, 1 page directive & role reference)
* `reStructuredText Demonstration <user/rst/demo.html>`_ (a
demonstration of most reStructuredText features; you can also have a
look at the `text source <user/rst/demo.txt>`__)
Editor support:
* `Emacs support for reStructuredText <user/emacs.html>`_
.. _ref:
``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 <ref/doctree.html>`__ (incomplete)
* `Docutils Transforms <ref/transforms.html>`__
* `Docutils Generic DTD <ref/docutils.dtd>`__
* `OASIS XML Exchange Table Model Declaration Module
<ref/soextblx.dtd>`__ (CALS tables DTD module)
Although not in the "ref" directory, `PEP 258`_ is a must-read
reference for any Docutils developer.
reStructuredText_:
* `An Introduction to reStructuredText <ref/rst/introduction.html>`__
(includes the `Goals <ref/rst/introduction.html#goals>`__ and
`History <ref/rst/introduction.html#history>`__ of reStructuredText)
* `reStructuredText Markup Specification <ref/rst/restructuredtext.html>`__
* `reStructuredText Directives <ref/rst/directives.html>`__
* `reStructuredText Interpreted Text Roles <ref/rst/roles.html>`__
* `reStructuredText Standard Definition Files
<ref/rst/definitions.html>`_
Prehistoric:
* `Setext Documents Mirror
<http://docutils.sourceforge.net/mirror/setext.html>`__
.. _peps:
``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.
__ peps/pep-0256.html
__ http://www.python.org/peps/pep-0256.html
__ peps/pep-0257.html
__ http://www.python.org/peps/pep-0257.html
.. _PEP 258:
__ peps/pep-0258.html
__ http://www.python.org/peps/pep-0258.html
__ peps/pep-0287.html
__ http://www.python.org/peps/pep-0287.html
.. _master repository: http://www.python.org/peps/
.. _api:
``api/``: API Reference Material for Client-Developers
======================================================
* `The Docutils Publisher <api/publisher.html>`__
* `Inside A Docutils Command-Line Front-End Tool <api/cmdline-tool.html>`__
* `Docutils Runtime Settings <api/runtime-settings.html>`__
* (`Docutils Transforms <ref/transforms.html>`__ should be moved here)
`PEP 258`_ is an overview of the architecture of Docutils.
.. _howto:
``howto/``: Instructions for Developers
=======================================
* **Security:** `Deploying Docutils Securely <howto/security.html>`__
* `Writing HTML (CSS) Stylesheets for Docutils
<howto/html-stylesheets.html>`__
* `Docutils Internationalization <howto/i18n.html>`__
* `Creating reStructuredText Directives <howto/rst-directives.html>`__
* `Creating reStructuredText Interpreted Text Roles
<howto/rst-roles.html>`__
.. _dev:
``dev/``: Development Notes and Plans for Core-Developers
=========================================================
Docutils-general:
* `Docutils Hacker's Guide <dev/hacking.html>`__
* `Docutils Distributor's Guide <dev/distributing.html>`__
* `Docutils To Do List <dev/todo.html>`__
* `Docutils Project Policies <dev/policies.html>`__
* `Docutils Web Site <dev/website.html>`__
* `Docutils Release Procedure <dev/release.html>`__
* `The Docutils Subversion Repository <dev/repository.html>`__
* `Docutils Testing <dev/testing.html>`__
* `Docstring Semantics <dev/semantics.html>`__ (incomplete)
* `Python Source Reader <dev/pysource.html>`_ (incomplete)
* `Docutils Python DTD <dev/pysource.dtd>`_ (experimental)
* `Plan for Enthought API Documentation Tool <dev/enthought-plan.html>`_
* `Enthought API Documentation Tool RFP <dev/enthought-rfp.html>`_
reStructuredText_:
* `A Record of reStructuredText Syntax Alternatives
<dev/rst/alternatives.html>`__
* `Problems With StructuredText <dev/rst/problems.html>`__
..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
End:
|
