1===============================
2 README: Docutils 0.17.1
3===============================
4
5:Author: David Goodger
6:Contact: goodger@python.org
7:Date: $Date: 2021-04-17 14:41:26 +0200 (Sa, 17. Apr 2021) $
8:Web site: http://docutils.sourceforge.net/
9:Copyright: This document has been placed in the public domain.
10
11.. contents::
12
13
14Quick-Start
15===========
16
17This is for those who want to get up & running quickly.
18
191. Docutils requires Python, available from
20 http://www.python.org/.
21
22 See Requirements_ below for details.
23
242. Install the latest stable release from PyPi with pip_::
25
26 python -m pip install docutils
27
28 To install a pre-relase, append the option ``--pre``.
29 To install a `development version`_, follow the instructions in
30 section `Installation`_ below.
31
323. Use the `front-end scripts`_ to convert reStructuredText documents.
33 Try for example::
34
35 rst2html.py FAQ.txt FAQ.html (Unix)
36 python tools/rst2html.py FAQ.txt FAQ.html (Windows)
37
38 See Usage_ below for details.
39
40.. _pip: https://pypi.org/project/pip/
41
42
43Purpose
44=======
45
46The purpose of the Docutils project is to create a set of tools for
47processing plaintext documentation into useful formats, such as HTML,
48LaTeX, troff (man pages), OpenOffice, and native XML. Support for the
49following sources has been implemented:
50
51* Standalone files.
52
53* `PEPs (Python Enhancement Proposals)`_.
54
55Support for the following sources is planned:
56
57* Inline documentation from Python modules and packages, extracted
58 with namespace context.
59
60* Email (RFC-822 headers, quoted excerpts, signatures, MIME parts).
61
62* Wikis, with global reference lookups of "wiki links".
63
64* Compound documents, such as multiple chapter files merged into a
65 book.
66
67* And others as discovered.
68
69.. _PEPs (Python Enhancement Proposals):
70 http://www.python.org/peps/pep-0012.html
71
72
73Requirements
74============
75
76To run the code, Python_ must be installed.
77
78* Docutils 0.16 and later supports Python 2.7 and 3.5+ natively. [#2to3]_
79* Docutils 0.14 dropped Python 2.4, 2.5, 3.1 and 3.2 support.
80* Docutils 0.10 dropped Python 2.3 support.
81* From version 0.6, Docutils is compatible with Python 3. [#2to3]_
82* For Docutils 0.5, Python 2.2.1+ is required.
83* Up to Docutils 0.4, Python 2.1 is required.
84
85.. [#2to3] Up to version 0.15, the Docutils codebase was translated
86 "on-demand" using the 2to3 tool.
87
88Recommendations
89---------------
90
91Docutils uses the following packages for enhanced functionality, if they
92are installed:
93
94* Installation_ is usually done with pip_ or setuptools_.
95
96* The `Python Imaging Library`_, or PIL, is used for some image
97 manipulation operations.
98
99* The `Pygments`_ package provides syntax highlight of "code" directives
100 and roles.
101
102* The `recommonmark`_ parser is used to parse input in Markdown format.
103
104The `Docutils Link List <docs/user/links.html>`__ records projects that
105users of Docutils and reStructuredText may find useful.
106
107.. _Python: http://www.python.org/.
108.. _Python Imaging Library: http://www.pythonware.com/products/pil/
109.. _Pygments: https://pypi.org/project/Pygments/
110.. _setuptools: https://pypi.org/project/setuptools/
111.. _recommonmark: https://github.com/rtfd/recommonmark
112
113
114Development version
115===================
116
117While we are trying to follow a "release early & often" policy,
118features are added frequently. Since the code in the repository_
119is usually in a bug-free state, we recommend using a current snapshot
120or a working copy.
121
122To get a _`snapshot`, go to the code page and click the download snapshot
123button:
124
125* Docutils code, documentation, front-end tools, and tests:
126 https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/
127
128* Sandbox (experimental, contributed code):
129 https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/sandbox/
130
131To keep up to date on the latest developments, download fresh copies of the
132snapshots regularly or use a `working copy of the Docutils code repository`__.
133
134Continue with the `Installation`_ instructions below.
135
136.. _repository: docs/dev/repository.html
137__ docs/dev/repository.html#checking-out-the-repository
138
139Installation
140============
141
142Steps to install Docutils from source:
143
144* Go to the directory containing the file ``setup.py``.
145
146 A snapshot_ must be unpacked in a temporary directory (**not** directly in
147 Python's ``site-packages``) first.
148
149* Run ``setup.py install``. [#setup-requires-setuptools]_
150 On Windows systems it may be sufficient to double-click ``install.py``.
151
152.. [#setup-requires-setuptools] ``setup.py`` requires the `setuptools`_
153 package. For a manual install see the options in `Setting up for Docutils
154 development`__.
155
156 __ docs/dev/policies.html#setting-up-for-docutils-development
157
158Optional steps:
159
160* `running the test suite`_
161
162* `converting the documentation`_
163
164OS-specific installation instructions follow.
165
166
167GNU/Linux, BSDs, Unix, Mac OS X, etc.
168-------------------------------------
169
1701. Open a shell.
171
1722. Go to the directory containing ``setup.py``::
173
174 cd <archive_directory_path>
175
1763. Install the package (you may need root permissions to complete this
177 step)::
178
179 su
180 (enter admin password)
181 python setup.py install
182
183 If the python executable isn't on your path, you'll have to specify
184 the complete path, such as ``/usr/local/bin/python``.
185
186 To install for a specific Python version, use this version in the
187 setup call, e.g. ::
188
189 python3.7 setup.py install
190
191 To install for different Python versions, repeat step 3 for every
192 required version. The last installed version will be used in the
193 `shebang line`_ of the ``rst2*.py`` wrapper scripts.
194
195 .. _shebang line: http://en.wikipedia.org/wiki/Shebang_%28Unix%29
196
197Windows
198-------
199
200Just double-click ``install.py``. If this doesn't work, try the
201following:
202
2031. Open a DOS Box (Command Shell, MS-DOS Prompt, or whatever they're
204 calling it these days).
205
2062. Go to the directory created by expanding the archive::
207
208 cd <archive_directory_path>
209
2103. Install the package::
211
212 <path_to_python.exe>\python setup.py install
213
214 To install for a specific python version, specify the Python
215 executable for this version.
216
217 To install for different Python versions, repeat step 3 for every
218 required version.
219
220
221Usage
222=====
223
224There are many front-end tools in the unpacked "tools" subdirectory.
225Installation under Unix places copies in the PATH.
226You may want to begin with the "rst2html.py" front-end tool. Most
227tools take up to two arguments, the source path and destination path,
228with STDIN and STDOUT being the defaults. Use the ``--help`` option to
229the front-end tools for details on options and arguments. See
230`Docutils Front-End Tools`_ for full documentation.
231
232The package modules are continually growing and evolving. The
233``docutils.statemachine`` module is usable independently. It contains
234extensive inline documentation (in reStructuredText format of course).
235
236Contributions are welcome!
237
238.. _front-end scripts:
239.. _Docutils Front-End Tools: docs/user/tools.html
240
241Project Files & Directories
242===========================
243
244* README.txt: You're reading it.
245
246* COPYING.txt: Public Domain Dedication and copyright details for
247 non-public-domain files (most are PD).
248
249* FAQ.txt: Frequently Asked Questions (with answers!).
250
251* RELEASE-NOTES.txt: Summary of the major changes in recent releases.
252
253* HISTORY.txt: A detailed change log, for the current and all previous
254 project releases.
255
256* BUGS.txt: Known bugs, and how to report a bug.
257
258* THANKS.txt: List of contributors.
259
260* setup.py: Installation script. See "Installation" below.
261
262* install.py: Quick & dirty installation script. Just run it. For
263 any kind of customization or help though, setup.py must be used.
264
265* docutils: The project source directory, installed as a Python
266 package.
267
268* docs: The project documentation directory. Read ``docs/index.txt``
269 for an overview.
270
271* docs/user: The project user documentation directory. Contains the
272 following documents, among others:
273
274 - docs/user/tools.txt: Docutils Front-End Tools
275 - docs/user/latex.txt: Docutils LaTeX Writer
276 - docs/user/rst/quickstart.txt: A ReStructuredText Primer
277 - docs/user/rst/quickref.html: Quick reStructuredText (HTML only)
278
279* docs/ref: The project reference directory.
280 ``docs/ref/rst/restructuredtext.txt`` is the reStructuredText
281 reference.
282
283* licenses: Directory containing copies of license files for
284 non-public-domain files.
285
286* tools: Directory for Docutils front-end tools. See
287 ``docs/user/tools.txt`` for documentation.
288
289* test: Unit tests. Not required to use the software, but very useful
290 if you're planning to modify it. See `Running the Test Suite`_
291 below.
292
293
294Converting the documentation
295============================
296
297After unpacking and installing the Docutils package, the following
298shell commands will generate HTML for all included documentation::
299
300 cd <archive_directory_path>/tools
301 ./buildhtml.py ../
302
303On Windows systems, type::
304
305 cd <archive_directory_path>\tools
306 python buildhtml.py ..
307
308The final directory name of the ``<archive_directory_path>`` is
309"docutils" for snapshots. For official releases, the directory may be
310called "docutils-X.Y.Z", where "X.Y.Z" is the release version.
311Alternatively::
312
313 cd <archive_directory_path>
314 tools/buildhtml.py --config=tools/docutils.conf (Unix)
315 python tools\buildhtml.py --config=tools\docutils.conf (Windows)
316
317Some files may generate system messages (warnings and errors). The
318``docs/user/rst/demo.txt`` file (under the archive directory) contains
319five intentional errors. (They test the error reporting mechanism!)
320
321
322Running the Test Suite
323======================
324
325The test suite is documented in `Docutils Testing`_ (docs/dev/testing.txt).
326
327To run the entire test suite, open a shell and use the following
328commands::
329
330 cd <archive_directory_path>/test
331 ./alltests.py
332
333Under Windows, type::
334
335 cd <archive_directory_path>\test
336 python alltests.py
337
338
339You should see a long line of periods, one for each test, and then a
340summary like this::
341
342 Ran 1111 tests in 24.653s
343
344 OK
345 Elapsed time: 26.189 seconds
346
347The number of tests will grow over time, and the times reported will
348depend on the computer running the tests. The difference between the
349two times represents the time required to set up the tests (import
350modules, create data structures, etc.).
351
352If any of the tests fail, please `open a bug report`_ or `send an email`_
353(see `Bugs <BUGS.html>`_).
354Please include all relevant output, information about your operating
355system, Python version, and Docutils version. To see the Docutils
356version, use one of the ``rst2*`` front ends or ``tools/quicktest.py``
357with the ``--version`` option, e.g.::
358
359 cd ../tools
360 ./quicktest.py --version
361
362Windows users type these commands::
363
364 cd ..\tools
365 python quicktest.py --version
366
367
368.. _Docutils Testing: http://docutils.sourceforge.net/docs/dev/testing.html
369.. _open a bug report:
370 http://sourceforge.net/p/docutils/bugs/
371.. _send an email: mailto:docutils-users@lists.sourceforge.net
372 ?subject=Test%20suite%20failure
373.. _web interface: https://sourceforge.net/p/docutils/mailman/
374
375
376Getting Help
377============
378
379If you have questions or need assistance with Docutils or
380reStructuredText, please post a message to the Docutils-users_ mailing
381list.
382
383.. _Docutils-users: docs/user/mailing-lists.html#docutils-users
384
385
386..
387 Local Variables:
388 mode: indented-text
389 indent-tabs-mode: nil
390 sentence-end-double-space: t
391 fill-column: 70
392 End:
393