6 :Contact: goodger@python.org
8 :Web site: http://docutils.sourceforge.net/
9 :Copyright: This document has been placed in the public domain.
17 This is for those who want to get up & running quickly. Read on for
20 1. Get and install the latest release of Python, available from
22 http://www.python.org/
24 Docutils is compatible with Python versions from 2.3 up to 2.6 and
25 version 3.1. (Support for Python 3 is new and might still have some
28 2. Use the latest Docutils code. Get the code from Subversion or from
31 http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/docutils/?view=tar
33 See `Releases & Snapshots`_ below for details.
35 3. Unpack the tarball in a temporary directory (**not** directly in
36 Python's ``site-packages``) and run ``setup.py install`` or
37 ``install.py`` with admin rights. On Windows systems it may be
38 sufficient to double-click ``install.py``. On Unix or Mac OS X,
42 (enter admin password)
45 Docutils will only work with Python 3, if installed with a Python
46 version >= 3. If your default Python version is 2.x, also call
47 ``python3 setup.py install`` from the temporary directory.
48 See Installation_ below for details.
50 4. Use a front-end tool from the "tools" subdirectory of the same
51 directory as in step 3. For example::
54 ./rst2html.py ../FAQ.txt ../FAQ.html (Unix)
55 python rst2html.py ..\FAQ.txt ..\FAQ.html (Windows)
57 See Usage_ below for details.
63 The purpose of the Docutils project is to create a set of tools for
64 processing plaintext documentation into useful formats, such as HTML,
65 XML, and LaTeX. Support for the following sources has been
70 * `PEPs (Python Enhancement Proposals)`_.
72 Support for the following sources is planned:
74 * Inline documentation from Python modules and packages, extracted
75 with namespace context.
77 * Email (RFC-822 headers, quoted excerpts, signatures, MIME parts).
79 * Wikis, with global reference lookups of "wiki links".
81 * Compound documents, such as multiple chapter files merged into a
84 * And others as discovered.
86 .. _PEPs (Python Enhancement Proposals):
87 http://www.python.org/peps/pep-0012.html
93 While we are trying to follow a "release early & often" policy,
94 features are added very frequently. Since the code in the Subversion
95 repository is usually in a bug-free state, we recommend that you use
96 the current snapshot (which is usually updated within an hour of
97 changes being committed to the repository):
99 * Snapshot of Docutils code, documentation, front-end tools, and
101 http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/docutils/?view=tar
103 * Snapshot of the Sandbox (experimental, contributed code):
104 http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/sandbox/?view=tar
106 To keep up to date on the latest developments, download fresh copies
107 of the snapshots regularly. New functionality is being added weekly,
108 sometimes daily. (There's also the `Subversion repository`_.)
110 .. _Subversion repository: docs/dev/repository.html
116 To run the code, Python 2.3 or later must already be installed.
117 Python is available from
118 http://www.python.org/.
120 The `Python Imaging Library`, or PIL, is used for some image
121 manipulation operations if it is installed.
123 .. _Python Imaging Library: http://www.pythonware.com/products/pil/
124 .. _Optik: http://optik.sourceforge.net/
127 Project Files & Directories
128 ===========================
130 * README.txt: You're reading it.
132 * COPYING.txt: Public Domain Dedication and copyright details for
133 non-public-domain files (most are PD).
135 * FAQ.txt: Frequently Asked Questions (with answers!).
137 * RELEASE-NOTES.txt: Summary of the major changes in recent releases.
139 * HISTORY.txt: A detailed change log, for the current and all previous
142 * BUGS.txt: Known bugs, and how to report a bug.
144 * THANKS.txt: List of contributors.
146 * setup.py: Installation script. See "Installation" below.
148 * install.py: Quick & dirty installation script. Just run it. For
149 any kind of customization or help though, setup.py must be used.
151 * docutils: The project source directory, installed as a Python
154 * extras: Directory for third-party modules that Docutils depends on
155 (roman.py). These are only installed if
156 they're not already present.
158 * docs: The project documentation directory. Read ``docs/index.txt``
161 * docs/user: The project user documentation directory. Contains the
162 following documents, among others:
164 - docs/user/tools.txt: Docutils Front-End Tools
165 - docs/user/latex.txt: Docutils LaTeX Writer
166 - docs/user/rst/quickstart.txt: A ReStructuredText Primer
167 - docs/user/rst/quickref.html: Quick reStructuredText (HTML only)
169 * docs/ref: The project reference directory.
170 ``docs/ref/rst/restructuredtext.txt`` is the reStructuredText
173 * licenses: Directory containing copies of license files for
174 non-public-domain files.
176 * tools: Directory for Docutils front-end tools. See
177 ``docs/user/tools.txt`` for documentation.
179 * test: Unit tests. Not required to use the software, but very useful
180 if you're planning to modify it. See `Running the Test Suite`_
187 The first step is to expand the ``.tgz`` archive in a temporary
188 directory (**not** directly in Python's ``site-packages``). It
189 contains a distutils setup file "setup.py". OS-specific installation
193 GNU/Linux, BSDs, Unix, Mac OS X, etc.
194 -------------------------------------
198 2. Go to the directory created by expanding the archive::
200 cd <archive_directory_path>
202 3. Install the package::
204 python setup.py install
206 If the python executable isn't on your path, you'll have to specify
207 the complete path, such as /usr/local/bin/python. You may need
208 root permissions to complete this step.
210 To install for a specific python version, use this version in the
213 python3.1 setup.py install
219 Just double-click ``install.py``. If this doesn't work, try the
222 1. Open a DOS Box (Command Shell, MS-DOS Prompt, or whatever they're
223 calling it these days).
225 2. Go to the directory created by expanding the archive::
227 cd <archive_directory_path>
229 3. Install the package::
231 <path_to_python.exe>\python setup.py install
233 To install for a specific python version, specify the Python
234 executable for this version.
237 Python 3 peculiarities
238 ----------------------
240 If called from Python 3, setup.py, in addition to copying the sources
241 to the right place, will also convert them using 2to3 to Python 3
244 * If you want to test or develop Docutils, also run ``python3 setup.py
245 build``. This will generate Python 3 compatible sources, tests and
246 developer tools in the build directory. Do changes on the Python 2
247 versions of the sources and re-run the build command. This works
248 incrementally, so if you change one file it will only reconvert that
249 file the next time you run setup.py build.
255 After unpacking and installing the Docutils package, the following
256 shell commands will generate HTML for all included documentation::
258 cd <archive_directory_path>/tools
261 On Windows systems, type::
263 cd <archive_directory_path>\tools
264 python buildhtml.py ..
266 The final directory name of the ``<archive_directory_path>`` is
267 "docutils" for snapshots. For official releases, the directory may be
268 called "docutils-X.Y.Z", where "X.Y.Z" is the release version.
271 cd <archive_directory_path>
272 tools/buildhtml.py --config=tools/docutils.conf (Unix)
273 python tools\buildhtml.py --config=tools\docutils.conf (Windows)
275 With Python 3, call::
277 build/<Python-3-subdir>/tools/buildhtml.py --config=tools/docutils.conf
279 Some files may generate system messages (warnings and errors). The
280 ``docs/user/rst/demo.txt`` file (under the archive directory) contains
281 five intentional errors. (They test the error reporting mechanism!)
283 There are many front-end tools in the unpacked "tools" subdirectory.
284 You may want to begin with the "rst2html.py" front-end tool. Most
285 tools take up to two arguments, the source path and destination path,
286 with STDIN and STDOUT being the defaults. Use the "--help" option to
287 the front-end tools for details on options and arguments. See
288 Docutils Front-End Tools (``docs/user/tools.txt``) for full documentation.
290 The package modules are continually growing and evolving. The
291 ``docutils.statemachine`` module is usable independently. It contains
292 extensive inline documentation (in reStructuredText format of course).
294 Contributions are welcome!
297 Running the Test Suite
298 ======================
300 To run the entire test suite, after installation_ open a shell and use
301 the following commands::
303 cd <archive_directory_path>/test
306 Under Windows, type::
308 cd <archive_directory_path>\test
311 For testing with Python 3 use the converted test suite::
313 cd <archive_directory_path>/build/<Python-3-subdir>/test
317 You should see a long line of periods, one for each test, and then a
320 Ran 1111 tests in 24.653s
323 Elapsed time: 26.189 seconds
325 The number of tests will grow over time, and the times reported will
326 depend on the computer running the tests. The difference between the
327 two times represents the time required to set up the tests (import
328 modules, create data structures, etc.).
330 If any of the tests fail, please `open a bug report`_, `send email`_,
331 or post a message via the `web interface`_ (see `Bugs <BUGS.html>`_).
332 Please include all relevant output, information about your operating
333 system, Python version, and Docutils version. To see the Docutils
334 version, use one of the ``rst2*`` front ends or ``tools/quicktest.py``
335 with the ``--version`` option, e.g.::
338 ./quicktest.py --version
340 Windows users type these commands::
343 python quicktest.py --version
345 Python 3 users must use ``build/<Python-3-subdir>/tools/quicktest.py``.
348 .. _open a bug report:
349 http://sourceforge.net/tracker/?group_id=38414&atid=422030
350 .. _send email: mailto:docutils-users@lists.sourceforge.net
351 ?subject=Test%20suite%20failure
352 .. _web interface: http://post.gmane.org/post.php
353 ?group=gmane.text.docutils.user&subject=Test+suite+failure
359 If you have questions or need assistance with Docutils or
360 reStructuredText, please post a message to the Docutils-users_ mailing
363 .. _Docutils-users: docs/user/mailing-lists.html#docutils-users
369 indent-tabs-mode: nil
370 sentence-end-double-space: t