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.7 and
25 versions 3.1 and 3.2. (Support for Python 3 is new and might still
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. (There's also the `Subversion repository`_.)
109 .. _Subversion repository: docs/dev/repository.html
115 To run the code, Python 2.3 or later must already be installed.
116 Python is available from
117 http://www.python.org/.
119 Docutils uses the following packages for enhanced functionality, if they are
122 * The `Python Imaging Library`, or PIL, is used for some image
123 manipulation operations.
125 * The `Pygments`_ syntax highlighter is used for content of `code`
126 directives and roles.
128 .. _Python Imaging Library: http://www.pythonware.com/products/pil/
129 .. _pygments: http://pygments.org/
131 Project Files & Directories
132 ===========================
134 * README.txt: You're reading it.
136 * COPYING.txt: Public Domain Dedication and copyright details for
137 non-public-domain files (most are PD).
139 * FAQ.txt: Frequently Asked Questions (with answers!).
141 * RELEASE-NOTES.txt: Summary of the major changes in recent releases.
143 * HISTORY.txt: A detailed change log, for the current and all previous
146 * BUGS.txt: Known bugs, and how to report a bug.
148 * THANKS.txt: List of contributors.
150 * setup.py: Installation script. See "Installation" below.
152 * install.py: Quick & dirty installation script. Just run it. For
153 any kind of customization or help though, setup.py must be used.
155 * docutils: The project source directory, installed as a Python
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.
236 Developing under Python 3
237 -------------------------
239 Under Python 3, installing with ``setup.py`` converts the source to Python 3
240 compatible code before installing. If you want to test or develop Docutils,
241 also run ``python3 setup.py build``. This will generate Python 3 compatible
242 sources, in the ``build/`` sub-directory, tests in ``tests3/``, and
243 developer tools in ``tools3``.
245 Do changes on the Python 2 versions of the sources and re-run the build
246 command. This works incrementally, so if you change one file it will only
247 reconvert that file the next time you run setup.py build.
253 After unpacking and installing the Docutils package, the following
254 shell commands will generate HTML for all included documentation::
256 cd <archive_directory_path>/tools
259 On Windows systems, type::
261 cd <archive_directory_path>\tools
262 python buildhtml.py ..
264 The final directory name of the ``<archive_directory_path>`` is
265 "docutils" for snapshots. For official releases, the directory may be
266 called "docutils-X.Y.Z", where "X.Y.Z" is the release version.
269 cd <archive_directory_path>
270 tools/buildhtml.py --config=tools/docutils.conf (Unix)
271 python tools\buildhtml.py --config=tools\docutils.conf (Windows)
273 With Python 3, call::
275 build/<Python-3-subdir>/tools/buildhtml.py --config=tools/docutils.conf
277 Some files may generate system messages (warnings and errors). The
278 ``docs/user/rst/demo.txt`` file (under the archive directory) contains
279 five intentional errors. (They test the error reporting mechanism!)
281 There are many front-end tools in the unpacked "tools" subdirectory.
282 You may want to begin with the "rst2html.py" front-end tool. Most
283 tools take up to two arguments, the source path and destination path,
284 with STDIN and STDOUT being the defaults. Use the "--help" option to
285 the front-end tools for details on options and arguments. See
286 Docutils Front-End Tools (``docs/user/tools.txt``) for full documentation.
288 The package modules are continually growing and evolving. The
289 ``docutils.statemachine`` module is usable independently. It contains
290 extensive inline documentation (in reStructuredText format of course).
292 Contributions are welcome!
295 Running the Test Suite
296 ======================
298 To run the entire test suite, after installation_ open a shell and use
299 the following commands::
301 cd <archive_directory_path>/test
304 Under Windows, type::
306 cd <archive_directory_path>\test
309 For testing with Python 3 use the converted test suite::
311 cd <archive_directory_path>/test3
315 You should see a long line of periods, one for each test, and then a
318 Ran 1111 tests in 24.653s
321 Elapsed time: 26.189 seconds
323 The number of tests will grow over time, and the times reported will
324 depend on the computer running the tests. The difference between the
325 two times represents the time required to set up the tests (import
326 modules, create data structures, etc.).
328 If any of the tests fail, please `open a bug report`_, `send email`_,
329 or post a message via the `web interface`_ (see `Bugs <BUGS.html>`_).
330 Please include all relevant output, information about your operating
331 system, Python version, and Docutils version. To see the Docutils
332 version, use one of the ``rst2*`` front ends or ``tools/quicktest.py``
333 with the ``--version`` option, e.g.::
336 ./quicktest.py --version
338 Windows users type these commands::
341 python quicktest.py --version
343 For Python 3, the path is ``tools3/quicktest.py``.
346 .. _open a bug report:
347 http://sourceforge.net/tracker/?group_id=38414&atid=422030
348 .. _send email: mailto:docutils-users@lists.sourceforge.net
349 ?subject=Test%20suite%20failure
350 .. _web interface: http://post.gmane.org/post.php
351 ?group=gmane.text.docutils.user&subject=Test+suite+failure
357 If you have questions or need assistance with Docutils or
358 reStructuredText, please post a message to the Docutils-users_ mailing
361 .. _Docutils-users: docs/user/mailing-lists.html#docutils-users
367 indent-tabs-mode: nil
368 sentence-end-double-space: t