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 Python 2.3 or later is required. Docutils is compatible with
27 2. Use the latest Docutils code. Get the code from Subversion or from
30 http://docutils.sf.net/docutils-snapshot.tgz
32 See `Releases & Snapshots`_ below for details.
34 3. Unpack the tarball in a temporary directory (**not** directly in
35 Python's ``site-packages``) and run ``install.py`` with admin
36 rights. On Windows systems it may be sufficient to double-click
37 ``install.py``. On Unix or Mac OS X, type::
40 (enter admin password)
43 See Installation_ below for details.
45 4. Use a front-end tool from the "tools" subdirectory of the same
46 directory as in step 3. For example::
49 ./rst2html.py ../FAQ.txt ../FAQ.html (Unix)
50 python rst2html.py ..\FAQ.txt ..\FAQ.html (Windows)
52 See Usage_ below for details.
58 The purpose of the Docutils project is to create a set of tools for
59 processing plaintext documentation into useful formats, such as HTML,
60 XML, and LaTeX. Support for the following sources has been
65 * `PEPs (Python Enhancement Proposals)`_.
67 Support for the following sources is planned:
69 * Inline documentation from Python modules and packages, extracted
70 with namespace context.
72 * Email (RFC-822 headers, quoted excerpts, signatures, MIME parts).
74 * Wikis, with global reference lookups of "wiki links".
76 * Compound documents, such as multiple chapter files merged into a
79 * And others as discovered.
81 .. _PEPs (Python Enhancement Proposals):
82 http://www.python.org/peps/pep-0012.html
88 While we are trying to follow a "release early & often" policy,
89 features are added very frequently. Since the code in the Subversion
90 repository is usually in a bug-free state, we recommend that you use
91 the current snapshot (which is usually updated within an hour of
92 changes being committed to the repository):
94 * Snapshot of Docutils code, documentation, front-end tools, and
95 tests: http://docutils.sf.net/docutils-snapshot.tgz
97 * Snapshot of the Sandbox (experimental, contributed code):
98 http://docutils.sf.net/docutils-sandbox-snapshot.tgz
100 To keep up to date on the latest developments, download fresh copies
101 of the snapshots regularly. New functionality is being added weekly,
102 sometimes daily. (There's also the `Subversion repository`_.)
104 .. _Subversion repository: docs/dev/repository.html
110 To run the code, Python 2.3 or later must already be installed.
111 Docutils is also compatible with Python 3. Python is available from
112 http://www.python.org/.
114 The `Python Imaging Library`, or PIL, is used for some image
115 manipulation operations if it is installed.
117 .. _Python Imaging Library: http://www.pythonware.com/products/pil/
118 .. _Optik: http://optik.sourceforge.net/
121 Project Files & Directories
122 ===========================
124 * README.txt: You're reading it.
126 * COPYING.txt: Public Domain Dedication and copyright details for
127 non-public-domain files (most are PD).
129 * FAQ.txt: Frequently Asked Questions (with answers!).
131 * RELEASE-NOTES.txt: Summary of the major changes in recent releases.
133 * HISTORY.txt: A detailed change log, for the current and all previous
136 * BUGS.txt: Known bugs, and how to report a bug.
138 * THANKS.txt: List of contributors.
140 * setup.py: Installation script. See "Installation" below.
142 * install.py: Quick & dirty installation script. Just run it. For
143 any kind of customization or help though, setup.py must be used.
145 * docutils: The project source directory, installed as a Python
148 * extras: Directory for third-party modules that Docutils depends on
149 (roman.py, optparse.py, textwrap.py). These are only installed if
150 they're not already present.
152 * docs: The project documentation directory. Read ``docs/index.txt``
155 * docs/user: The project user documentation directory. Contains the
156 following documents, among others:
158 - docs/user/tools.txt: Docutils Front-End Tools
159 - docs/user/latex.txt: Docutils LaTeX Writer
160 - docs/user/rst/quickstart.txt: A ReStructuredText Primer
161 - docs/user/rst/quickref.html: Quick reStructuredText (HTML only)
163 * docs/ref: The project reference directory.
164 ``docs/ref/rst/restructuredtext.txt`` is the reStructuredText
167 * licenses: Directory containing copies of license files for
168 non-public-domain files.
170 * tools: Directory for Docutils front-end tools. See
171 ``docs/user/tools.txt`` for documentation.
173 * test: Unit tests. Not required to use the software, but very useful
174 if you're planning to modify it. See `Running the Test Suite`_
181 The first step is to expand the ``.tgz`` archive in a temporary
182 directory (**not** directly in Python's ``site-packages``). It
183 contains a distutils setup file "setup.py". OS-specific installation
187 GNU/Linux, BSDs, Unix, Mac OS X, etc.
188 -------------------------------------
192 2. Go to the directory created by expanding the archive::
194 cd <archive_directory_path>
196 3. Install the package::
198 python setup.py install
200 If the python executable isn't on your path, you'll have to specify
201 the complete path, such as /usr/local/bin/python. You may need
202 root permissions to complete this step.
204 You can also just run install.py; it does the same thing.
210 Just double-click ``install.py``. If this doesn't work, try the
213 1. Open a DOS Box (Command Shell, MS-DOS Prompt, or whatever they're
214 calling it these days).
216 2. Go to the directory created by expanding the archive::
218 cd <archive_directory_path>
220 3. Install the package::
222 <path_to_python.exe>\python setup.py install
228 After unpacking and installing the Docutils package, the following
229 shell commands will generate HTML for all included documentation::
231 cd <archive_directory_path>/tools
234 On Windows systems, type::
236 cd <archive_directory_path>\tools
237 python buildhtml.py ..
239 The final directory name of the ``<archive_directory_path>`` is
240 "docutils" for snapshots. For official releases, the directory may be
241 called "docutils-X.Y.Z", where "X.Y.Z" is the release version.
244 cd <archive_directory_path>
245 tools/buildhtml.py --config=tools/docutils.conf (Unix)
246 python tools\buildhtml.py --config=tools\docutils.conf (Windows)
248 Some files may generate system messages (warnings and errors). The
249 ``docs/user/rst/demo.txt`` file (under the archive directory) contains
250 5 intentional errors. (They test the error reporting mechanism!)
252 There are many front-end tools in the unpacked "tools" subdirectory.
253 You may want to begin with the "rst2html.py" front-end tool. Most
254 tools take up to two arguments, the source path and destination path,
255 with STDIN and STDOUT being the defaults. Use the "--help" option to
256 the front-end tools for details on options and arguments. See
257 Docutils Front-End Tools (``docs/user/tools.txt``) for full documentation.
259 The package modules are continually growing and evolving. The
260 ``docutils.statemachine`` module is usable independently. It contains
261 extensive inline documentation (in reStructuredText format of course).
263 Contributions are welcome!
266 Running the Test Suite
267 ======================
269 To run the entire test suite, after installation_ open a shell and use
270 the following commands::
272 cd <archive_directory_path>/test
275 Under Windows, type::
277 cd <archive_directory_path>\test
280 You should see a long line of periods, one for each test, and then a
283 Ran 518 tests in 24.653s
286 Elapsed time: 26.189 seconds
288 The number of tests will grow over time, and the times reported will
289 depend on the computer running the tests. The difference between the
290 two times represents the time required to set up the tests (import
291 modules, create data structures, etc.).
293 If any of the tests fail, please `open a bug report`_, `send email`_,
294 or post a message via the `web interface`_. Please include all
295 relevant output, information about your operating system, Python
296 version, and Docutils version. To see the Docutils version, use these
297 commands in the shell::
300 ./quicktest.py --version
302 Windows users type these commands::
305 python quicktest.py --version
307 .. _open a bug report:
308 http://sourceforge.net/tracker/?group_id=38414&atid=422030
309 .. _send email: mailto:docutils-users@lists.sourceforge.net
310 ?subject=Test%20suite%20failure
311 .. _web interface: http://post.gmane.org/post.php
312 ?group=gmane.text.docutils.user&subject=Test+suite+failure
318 If you have questions or need assistance with Docutils or
319 reStructuredText, please post a message to the Docutils-users_ mailing
322 .. _Docutils-users: docs/user/mailing-lists.html#docutils-users
328 indent-tabs-mode: nil
329 sentence-end-double-space: t