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
239
240
241
242
243
244
245
246
247
248
|
==========================================
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 distribution: https://docutils.sourceforge.io/#download
.. header::
Docutils_ | Overview | About__ | Users__ | Reference__ | Developers__
.. _Docutils: https://docutils.sourceforge.io/
__ `project fundamentals`_
__ user_
__ ref_
__ howto_
.. contents::
Project Fundamentals
====================
These files are for all `Docutils stakeholders`_. They are kept at the
top level of the Docutils project directory.
.. class:: narrow run-in
:README_: Project overview: quick-start, requirements,
installation, and usage.
:COPYING_: 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.
:RELEASE-NOTES_: Summary of the major changes in recent releases and
notice of future incompatible changes.
:HISTORY_: Detailed change history log.
:THANKS_: Acknowledgements.
.. _README: ../README.html
.. _BUGS: ../BUGS.html
.. _COPYING: ../COPYING.html
.. _Docutils FAQ:
.. _FAQ: ../FAQ.html
.. _RELEASE-NOTES: ../RELEASE-NOTES.html
.. _HISTORY: ../HISTORY.html
.. _THANKS: ../THANKS.html
.. _docutils stakeholders:
.. class:: details
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.
.. _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:
* `Docutils HTML Writers <user/html.html>`__
* `Easy Slide Shows With reStructuredText & S5 <user/slide-shows.html>`__
* `Docutils LaTeX Writer <user/latex.html>`__
* `Man Page Writer for Docutils <user/manpage.html>`__
* `Docutils ODF/OpenOffice/odt Writer <user/odt.html>`__
`reStructuredText <https://docutils.sourceforge.io/rst.html>`_:
* `A ReStructuredText Primer <user/rst/quickstart.html>`__
(see also the `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)
* `Demonstration <user/rst/demo.html>`_
of most reStructuredText features
(see also the `text source <user/rst/demo.txt>`__)
Editor support:
* `Emacs support for reStructuredText <user/emacs.html>`_
.. _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 Generic DTD <ref/docutils.dtd>`__
* `OASIS XML Exchange Table Model Declaration Module
<ref/soextblx.dtd>`__ (CALS tables DTD module)
* `Docutils Design Specification`_ (PEP 258)
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>`_
* `LaTeX syntax for mathematics <ref/rst/mathematics.html>`__
(syntax used in "math" directive and role)
.. _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`_ developed
independent from the local versions after submission.
__ peps/pep-0256.html
__ peps/pep-0257.html
.. _PEP 258:
.. _Docutils Design Specification:
__ peps/pep-0258.html
__ peps/pep-0287.html
.. _master repository: https://peps.python.org
Prehistoric:
`Setext Documents Mirror`__
__ https://docutils.sourceforge.io/mirror/setext.html
.. _api:
API Reference Material for Client-Developers
============================================
`The Docutils Publisher <api/publisher.html>`__
entry points for using Docutils as a library
`Docutils Runtime Settings <api/runtime-settings.html>`__
configuration framework details
`Docutils Transforms <api/transforms.html>`__
change the document tree in-place (resolve references, …)
The `Docutils Design Specification`_ (PEP 258) is a must-read for any
Docutils developer.
.. _howto:
Instructions for Developers
===========================
:Security: `Deploying Docutils Securely <howto/security.html>`__
* `Inside A Docutils Command-Line Front-End Tool <howto/cmdline-tool.html>`__
* `Runtime Settings Processing <dev/runtime-settings-processing.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:
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>`_
* `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:
|
