File: README.txt

package info (click to toggle)
python-docutils 0.13.1%2Bdfsg-2
  • links: PTS, VCS
  • area: main
  • in suites: stretch
  • size: 8,728 kB
  • ctags: 7,259
  • sloc: python: 43,776; lisp: 13,142; xml: 1,644; sh: 164; makefile: 151
file content (414 lines) | stat: -rw-r--r-- 12,267 bytes parent folder | download
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
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
=======================
 README: Docutils 0.12
=======================

:Author: David Goodger
:Contact: goodger@python.org
:Date: $Date: 2014-07-07 04:36:36 +0200 (Mo, 07. Jul 2014) $
:Web site: http://docutils.sourceforge.net/
:Copyright: This document has been placed in the public domain.

.. contents::


Quick-Start on Debian systems
=============================

The reStructuredText tools are installed in the normal system path by the
Debian ``python-docutils`` package. To convert reStructuredText to another
format, use a shell command like::

       rst2html /usr/share/doc/python-docutils/FAQ.txt ./FAQ.html

See Usage_ below for details.

Quick-Start on other systems
============================

This is for those who want to get up & running quickly.

1. Docutils requires Python (version 2.4 or later), available from

     http://www.python.org/

   See Requirements_ below for details.

2. Use the latest Docutils code.  Get the code from the `Subversion
   repository`_ or from the snapshot:

     http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/docutils/?view=tar

   See `Releases & Snapshots`_ below for details.

3. Unpack the tarball in a temporary directory (**not** directly in
   Python's ``site-packages``), go to the directory created by expanding
   the archive, and run ``setup.py install`` with admin rights. On
   Windows systems it may be sufficient to double-click ``install.py``.

   See Installation_ below for details.

4. Use the front-end scripts to convert reStructuredText documents.
   Try for example::

       rst2html.py FAQ.txt FAQ.html         (Unix)
       python tools/rst2html.py FAQ.txt FAQ.html  (Windows)

   See Usage_ below for details.


Purpose
=======

The purpose of the Docutils project is to create a set of tools for
processing plaintext documentation into useful formats, such as HTML,
XML, and LaTeX.  Support for the following sources has been
implemented:

* Standalone files.

* `PEPs (Python Enhancement Proposals)`_.

Support for the following sources is planned:

* Inline documentation from Python modules and packages, extracted
  with namespace context.

* Email (RFC-822 headers, quoted excerpts, signatures, MIME parts).

* Wikis, with global reference lookups of "wiki links".

* Compound documents, such as multiple chapter files merged into a
  book.

* And others as discovered.

.. _PEPs (Python Enhancement Proposals):
   http://www.python.org/peps/pep-0012.html


Releases & Snapshots
====================

While we are trying to follow a "release early & often" policy,
features are added very frequently.  Since the code in the Subversion
repository is usually in a bug-free state, we recommend that you use
the current snapshot (which is usually updated within an hour of
changes being committed to the repository):

* Snapshot of Docutils code, documentation, front-end tools, and
  tests:
  http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/docutils/?view=tar

* Snapshot of the Sandbox (experimental, contributed code):
  http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/sandbox/?view=tar

To keep up to date on the latest developments, download fresh copies of
the snapshots regularly or use a working copy of the
`Subversion repository`_.

.. _Subversion repository: docs/dev/repository.html


Requirements
============

To run the code, Python_ must be installed.
Docutils is compatible with Python versions from 2.4 up to 2.7 and
versions 3.1 and 3.2 (cf. `Python 3 compatibility`_).

Docutils uses the following packages for enhanced functionality, if they are
installed:

* The `Python Imaging Library`_, or PIL, is used for some image
  manipulation operations.

* The `Pygments`_ syntax highlighter is used for content of `code`
  directives and roles.

.. _Python: http://www.python.org/.
.. _Python Imaging Library: http://www.pythonware.com/products/pil/
.. _Pygments: http://pygments.org/


Python 3 compatibility
----------------------

The Docutils codebase is written for Python 2 and uses "on-demand"
translation for `porting to Python 3`_.

* The `setup.py` script generates Python 3 compatible sources in
  ``build/`` and tests in ``tests3/`` sub-directories during
  installation_ with Python 3.

* The scripts in the ``tools/`` sub-directory work with all supported
  Python versions without conversion.

* To convert the sources without installing (e.g. for testing), run
  ``python3 setup.py build``.

* When editing the source, do changes on the Python 2 versions of the
  files and re-run the build command.

Using Docutils with Python 3.x is less tested and might still have some
issues.

.. _porting to Python 3: http://docs.python.org/py3k/howto/pyporting.html


Project Files & Directories
===========================

* README.txt: You're reading it.

* COPYING.txt: Public Domain Dedication and copyright details for
  non-public-domain files (most are PD).

* FAQ.txt: Frequently Asked Questions (with answers!).

* RELEASE-NOTES.txt: Summary of the major changes in recent releases.

* HISTORY.txt: A detailed change log, for the current and all previous
  project releases.

* BUGS.txt: Known bugs, and how to report a bug.

* THANKS.txt: List of contributors.

* setup.py: Installation script.  See "Installation" below.

* install.py: Quick & dirty installation script.  Just run it.  For
  any kind of customization or help though, setup.py must be used.

* docutils: The project source directory, installed as a Python
  package.

* docs: The project documentation directory.  Read ``docs/index.txt``
  for an overview.

* docs/user: The project user documentation directory.  Contains the
  following documents, among others:

  - docs/user/tools.txt: Docutils Front-End Tools
  - docs/user/latex.txt: Docutils LaTeX Writer
  - docs/user/rst/quickstart.txt: A ReStructuredText Primer
  - docs/user/rst/quickref.html: Quick reStructuredText (HTML only)

* docs/ref: The project reference directory.
  ``docs/ref/rst/restructuredtext.txt`` is the reStructuredText
  reference.

* licenses: Directory containing copies of license files for
  non-public-domain files.

* tools: Directory for Docutils front-end tools.  See
  ``docs/user/tools.txt`` for documentation.

* test: Unit tests.  Not required to use the software, but very useful
  if you're planning to modify it.  See `Running the Test Suite`_
  below.

Generated directories when installing under Python 3:

* build: Converted sources.

* test3: Converted tests.


Installation
============

The first step is to expand the ``.tgz`` archive in a temporary
directory (**not** directly in Python's ``site-packages``).  It
contains a distutils setup file "setup.py".  OS-specific installation
instructions follow.


GNU/Linux, BSDs, Unix, Mac OS X, etc.
-------------------------------------

1. Open a shell.

2. Go to the directory created by expanding the archive::

       cd <archive_directory_path>

3. Install the package (you may need root permissions to complete this
   step)::

       su
       (enter admin password)
       python setup.py install

   If the python executable isn't on your path, you'll have to specify
   the complete path, such as ``/usr/local/bin/python``.

   To install for a specific Python version, use this version in the
   setup call, e.g. ::

       python3.1 setup.py install

   To install for different Python versions, repeat step 3 for every
   required version. The last installed version will be used in the
   `shebang line`_ of the ``rst2*.py`` wrapper scripts.

   .. _shebang line: http://en.wikipedia.org/wiki/Shebang_%28Unix%29

Windows
-------

Just double-click ``install.py``.  If this doesn't work, try the
following:

1. Open a DOS Box (Command Shell, MS-DOS Prompt, or whatever they're
   calling it these days).

2. Go to the directory created by expanding the archive::

       cd <archive_directory_path>

3. Install the package::

       <path_to_python.exe>\python setup.py install

   To install for a specific python version, specify the Python
   executable for this version.

   To install for different Python versions, repeat step 3 for every
   required version.

Optional steps:

* `running the test suite`_

* `converting the documentation`_


Usage
=====

There are many front-end tools in the unpacked "tools" subdirectory.
Installation under Unix places copies in the PATH.
You may want to begin with the "rst2html.py" front-end tool.  Most
tools take up to two arguments, the source path and destination path,
with STDIN and STDOUT being the defaults.  Use the "--help" option to
the front-end tools for details on options and arguments.  See
Docutils Front-End Tools (``docs/user/tools.txt``) for full documentation.

On a Debian system the included tools (with the exception of quicktest.py
and the development tools in the dev/ directory) are installed into the
normal system path, so you can run ``rst2html.py`` with a command like::

    rst2html example.txt example.html

The package modules are continually growing and evolving.  The
``docutils.statemachine`` module is usable independently.  It contains
extensive inline documentation (in reStructuredText format of course).

Contributions are welcome!


Converting the documentation
============================

After unpacking and installing the Docutils package, the following
shell commands will generate HTML for all included documentation::

    cd <archive_directory_path>/tools
    ./buildhtml.py ../

On Windows systems, type::

    cd <archive_directory_path>\tools
    python buildhtml.py ..

The final directory name of the ``<archive_directory_path>`` is
"docutils" for snapshots.  For official releases, the directory may be
called "docutils-X.Y.Z", where "X.Y.Z" is the release version.
Alternatively::

    cd <archive_directory_path>
    tools/buildhtml.py --config=tools/docutils.conf          (Unix)
    python tools\buildhtml.py --config=tools\docutils.conf   (Windows)

Some files may generate system messages (warnings and errors).  The
``docs/user/rst/demo.txt`` file (under the archive directory) contains
five intentional errors.  (They test the error reporting mechanism!)


Running the Test Suite
======================

The test suite is documented in `Docutils Testing`_ (docs/dev/testing.txt).

To run the entire test suite, open a shell and use the following
commands::

    cd <archive_directory_path>/test
    ./alltests.py

Under Windows, type::

    cd <archive_directory_path>\test
    python alltests.py

For testing with Python 3 use the converted test suite::

    cd <archive_directory_path>/test3
    python3 alltests.py


You should see a long line of periods, one for each test, and then a
summary like this::

    Ran 1111 tests in 24.653s

    OK
    Elapsed time: 26.189 seconds

The number of tests will grow over time, and the times reported will
depend on the computer running the tests.  The difference between the
two times represents the time required to set up the tests (import
modules, create data structures, etc.).

If any of the tests fail, please `open a bug report`_, `send email`_,
or post a message via the `web interface`_ (see `Bugs <BUGS.html>`_).
Please include all relevant output, information about your operating
system, Python version, and Docutils version.  To see the Docutils
version, use one of the ``rst2*`` front ends or ``tools/quicktest.py``
with the ``--version`` option, e.g.::

    cd ../tools
    ./quicktest.py --version

Windows users type these commands::

    cd ..\tools
    python quicktest.py --version


.. _Docutils Testing: http://docutils.sourceforge.net/docs/dev/testing.html
.. _open a bug report:
   http://sourceforge.net/p/docutils/bugs/
.. _send email: mailto:docutils-users@lists.sourceforge.net
   ?subject=Test%20suite%20failure
.. _web interface: http://post.gmane.org/post.php
   ?group=gmane.text.docutils.user&subject=Test+suite+failure


Getting Help
============

If you have questions or need assistance with Docutils or
reStructuredText, please post a message to the Docutils-users_ mailing
list.

.. _Docutils-users: docs/user/mailing-lists.html#docutils-users


..
   Local Variables:
   mode: indented-text
   indent-tabs-mode: nil
   sentence-end-double-space: t
   fill-column: 70
   End: