6 :Contact: goodger@users.sourceforge.net
8 :Web site: http://docutils.sourceforge.net/
9 :Copyright: This document has been placed in the public domain.
14 Thank you for downloading the Python Docutils project archive. As
15 this is a work in progress, please check the project website for
16 updated working files (snapshots). This project should be considered
17 highly experimental; APIs are subject to change at any time.
23 This is for those who want to get up & running quickly. Read on for
26 1. Get and install the latest release of Python, available from
28 http://www.python.org/
30 Python 2.2 or later [1]_ is required; Python 2.2.2 or later is
33 2. Use the latest Docutils code. Get the code from CVS or from the
36 http://docutils.sf.net/docutils-snapshot.tgz
38 See `Releases & Snapshots`_ below for details.
40 3. Unpack the tarball in a temporary directory (**not** directly in
41 Python's ``site-packages``) and install with the standard ::
43 python setup.py install
45 See Installation_ below for details.
47 4. Use a front-end tool from the "tools" subdirectory of the same
48 directory as in step 3. For example::
51 ./rst2html.py ../FAQ.txt ../FAQ.html (Unix)
52 python rst2html.py ..\FAQ.txt ..\FAQ.html (Windows)
54 See Usage_ below for details.
60 The purpose of the Docutils project is to create a set of tools for
61 processing plaintext documentation into useful formats, such as HTML,
62 XML, and TeX. Support for the following sources has been implemented:
66 * `PEPs (Python Enhancement Proposals)`_.
68 Support for the following sources is planned:
70 * Inline documentation from Python modules and packages, extracted
71 with namespace context. **This is the focus of the current
74 * Email (RFC-822 headers, quoted excerpts, signatures, MIME parts).
76 * Wikis, with global reference lookups of "wiki links".
78 * Compound documents, such as multiple chapter files merged into a
81 * And others as discovered.
83 .. _PEPs (Python Enhancement Proposals):
84 http://www.python.org/peps/pep-0012.html
90 Putting together an official "Release" of Docutils is a significant
91 effort, so it isn't done that often. In the meantime, the CVS
92 snapshots always contain the latest code and documentation, usually
93 updated within an hour of changes being committed to the repository,
96 * Snapshot of Docutils code, documentation, front-end tools, and
97 tests: http://docutils.sf.net/docutils-snapshot.tgz
99 * Snapshot of the Sandbox (experimental, contributed code):
100 http://docutils.sf.net/docutils-sandbox-snapshot.tgz
102 * Snapshot of web files (the files that generate the web site):
103 http://docutils.sf.net/docutils-web-snapshot.tgz
105 To keep up to date on the latest developments, download fresh copies
106 of the snapshots regularly. New functionality is being added weekly,
107 sometimes daily. (There's also the CVS repository, and a mailing list
108 for CVS messages. See the web site [address above] or
109 docs/dev/policies.txt for details.)
115 To run the code, Python 2.2 or later [1]_ must already be installed.
116 The latest release is recommended. Python is available from
117 http://www.python.org/.
119 The `Python Imaging Library`, or PIL, is used for some image
120 manipulation operations if it is installed.
122 Docutils uses Greg Ward's Optik_/optparse option processing package.
123 It is included in the Docutils distribution. Python 2.3 and later
124 come with optparse in the standard library; in this case, the Docutils
125 copy is not installed.
127 .. [1] Python 2.1 may be used providing the compiler package is
128 installed. The compiler package can be found in the Tools/
129 directory of Python 2.1's source distribution.
131 .. _Python Imaging Library: http://www.pythonware.com/products/pil/
132 .. _Optik: http://optik.sourceforge.net/
135 Project Files & Directories
136 ===========================
138 * README.txt: You're reading it.
140 * COPYING.txt: Public Domain Dedication and copyright details for
141 non-public-domain files (most are PD).
143 * FAQ.txt: Docutils Frequently Asked Questions.
145 * HISTORY.txt: Release notes for the current and previous project
148 * setup.py: Installation script. See "Installation" below.
150 * install.py: Quick & dirty installation script. Just run it. For
151 any kind of customization or help though, setup.py must be used.
153 * docutils: The project source directory, installed as a Python
156 * extras: Directory for third-party modules that Docutils depends on.
157 These are only installed if they're not already present.
159 * docs: The project documentation directory. Read ``docs/index.txt``
160 for an overview, which is especially interesting for developers.
162 * docs/user: The project user documentation directory. Contains the
163 following documents, among others:
165 - docs/user/tools.txt: Docutils Front-End Tools
166 - docs/user/latex.txt: Docutils LaTeX Writer
167 - docs/user/rst/quickstart.txt: A ReStructuredText Primer
168 - docs/user/rst/quickref.html: Quick reStructuredText (HTML only)
170 * docs/ref: The project reference directory.
171 ``docs/ref/rst/restructuredtext.txt`` is the reStructuredText
174 * licenses: Directory containing copies of license files for
175 non-public-domain files.
177 * tools: Directory for Docutils front-end tools. See
178 ``docs/user/tools.txt`` for documentation.
180 * test: Unit tests. Not required to use the software, but very useful
181 if you're planning to modify it. See `Running the Test Suite`_
188 The first step is to expand the ``.tar.gz`` or ``.tgz`` archive in a
189 temporary directory (**not** directly in Python's ``site-packages``).
190 It contains a distutils setup file "setup.py". OS-specific
191 installation instructions follow.
194 GNU/Linux, BSDs, Unix, Mac OS X, etc.
195 -------------------------------------
199 2. Go to the directory created by expanding the archive::
201 cd <archive_directory_path>
203 3. Install the package::
205 python setup.py install
207 If the python executable isn't on your path, you'll have to specify
208 the complete path, such as /usr/local/bin/python. You may need
209 root permissions to complete this step.
211 You can also just run install.py; it does the same thing.
217 1. Open a DOS box (Command Shell, MSDOS Prompt, or whatever they're
218 calling it these days).
220 2. Go to the directory created by expanding the archive::
222 cd <archive_directory_path>
224 3. Install the package::
226 <path_to_python.exe>\python setup.py install
228 If your system is set up to run Python when you double-click on .py
229 files, you can run install.py to do the same as the above.
235 1. Open the folder containing the expanded archive.
237 2. Double-click on the file "setup.py", which should be a "Python
240 If the file isn't a "Python module", the line endings are probably
241 also wrong, and you will need to set up your system to recognize
242 ".py" file extensions as Python files. See
243 http://gotools.sourceforge.net/mac/python.html for detailed
244 instructions. Once set up, it's easiest to start over by expanding
247 3. The distutils options window will appear. From the "Command" popup
248 list choose "install", click "Add", then click "OK".
250 If install.py is a "Python module" (see step 2 above if it isn't), you
251 can run it (double-click) instead of the above. The distutils options
252 window will not appear.
258 After unpacking and installing the Docutils package, the following
259 shell commands will generate HTML for all included documentation::
261 cd <archive_directory_path>/tools
264 On Windows systems, type::
266 cd <archive_directory_path>\tools
267 python buildhtml.py ..
269 The final directory name of the ``<archive_directory_path>`` is
270 "docutils" for snapshots. For official releases, the directory may be
271 called "docutils-X.Y.Z", where "X.Y.Z" is the release version.
274 cd <archive_directory_path>
275 tools/buildhtml.py --config=tools/docutils.conf (Unix)
276 python tools\buildhtml.py --config=tools\docutils.conf (Windows)
278 Some files may generate system messages (warnings and errors). The
279 ``docs/user/rst/demo.txt`` file (under the archive directory) contains
280 5 intentional errors. (They test the error reporting mechanism!)
282 There are many front-end tools in the unpacked "tools" subdirectory.
283 You may want to begin with the "rst2html.py" front-end tool. Most
284 tools take up to two arguments, the source path and destination path,
285 with STDIN and STDOUT being the defaults. Use the "--help" option to
286 the front-end tools for details on options and arguments. See
287 Docutils Front-End Tools (``docs/user/tools.txt``) for full documentation.
289 The package modules are continually growing and evolving. The
290 ``docutils.statemachine`` module is usable independently. It contains
291 extensive inline documentation (in reStructuredText format of course).
293 Contributions are welcome!
296 Running the Test Suite
297 ======================
299 To run the entire test suite, after installation_ open a shell and use
300 the following commands::
302 cd <archive_directory_path>/test
305 Under Windows, type::
307 cd <archive_directory_path>\test
310 You should see a long line of periods, one for each test, and then a
313 Ran 518 tests in 24.653s
316 Elapsed time: 26.189 seconds
318 The number of tests will grow over time, and the times reported will
319 depend on the computer running the tests. The difference between the
320 two times represents the time required to set up the tests (import
321 modules, create data structures, etc.).
323 If any of the tests fail, please `open a bug report`_ or `send email`_
324 [2]_. Please include all relevant output, information about your
325 operating system, Python version, and Docutils version. To see the
326 Docutils version, use these commands in the shell::
329 ./quicktest.py --version
331 Windows users type these commands::
334 python quicktest.py --version
336 .. _open a bug report:
337 http://sourceforge.net/tracker/?group_id=38414&atid=422030
338 .. _send email: mailto:docutils-users@lists.sourceforge.net
339 ?subject=Docutils%20test%20suite%20failure
345 If you have questions or need assistance with Docutils or
346 reStructuredText, please `post a message`_ to the `Docutils-Users
349 .. [2] Due to overwhelming amounts of spam, the
350 docutils-users@lists.sourceforge.net mailing list has been set up
351 for subscriber posting only. Non-subscribers who post to
352 docutils-users will receive a message with "Subject: Your message
353 to Docutils-users awaits moderator approval". Legitimate messages
354 are accepted and posted as soon as possible (a list administrator
355 must verify the message manually). If you'd like to subscribe to
356 docutils-users, please visit
357 <http://lists.sourceforge.net/lists/listinfo/docutils-users>.
359 .. _post a message: mailto:docutils-users@lists.sourceforge.net
360 .. _Docutils-Users mailing list:
361 http://lists.sourceforge.net/lists/listinfo/docutils-users
367 indent-tabs-mode: nil
368 sentence-end-double-space: t