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 [#py21]_ 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 test.txt test.html
53 See Usage_ below for details.
59 The purpose of the Docutils project is to create a set of tools for
60 processing plaintext documentation into useful formats, such as HTML,
61 XML, and TeX. Support for the following sources has been implemented:
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. **This is the focus of the current
73 * Email (RFC-822 headers, quoted excerpts, signatures, MIME parts).
75 * Wikis, with global reference lookups of "wiki links".
77 * Compound documents, such as multiple chapter files merged into a
80 * And others as discovered.
82 .. _PEPs (Python Enhancement Proposals):
83 http://www.python.org/peps/pep-0012.html
89 Putting together an official "Release" of Docutils is a significant
90 effort, so it isn't done that often. In the meantime, the CVS
91 snapshots always contain the latest code and documentation, usually
92 updated within an hour of changes being committed to the repository,
95 * Snapshot of Docutils code, front-end tools, tests, documentation,
96 and specifications: http://docutils.sf.net/docutils-snapshot.tgz
98 * Snapshot of the Sandbox (experimental, contributed code):
99 http://docutils.sf.net/docutils-sandbox-snapshot.tgz
101 * Snapshot of web files (the files that generate the web site):
102 http://docutils.sf.net/docutils-web-snapshot.tgz
104 To keep up to date on the latest developments, download fresh copies
105 of the snapshots regularly. New functionality is being added weekly,
106 sometimes daily. (There's also the CVS repository, and a mailing list
107 for CVS messages. See the web site [address above] or spec/notes.txt
114 To run the code, Python 2.2 or later [#py21]_ must already be
115 installed. The latest release is recommended (2.2.2 as of this
116 writing). Python is available from http://www.python.org/.
118 The `Python Imaging Library`, or PIL, is used for some image
119 manipulation operations if it is installed.
121 Docutils uses Greg Ward's Optik_/optparse option processing package.
122 It is included in the Docutils distribution.
124 .. [#py21] Python 2.1 may be used providing the compiler package is
125 installed. The compiler package can be found in the Tools/
126 directory of Python 2.1's source distribution.
128 .. _Python Imaging Library: http://www.pythonware.com/products/pil/
129 .. _Optik: http://optik.sourceforge.net/
132 Project Files & Directories
133 ===========================
135 * README.txt: You're reading it.
137 * COPYING.txt: Public Domain Dedication and copyright details for
138 non-public-domain files (most are PD).
140 * FAQ.txt: Docutils Frequently Asked Questions.
142 * HISTORY.txt: Release notes for the current and previous project
145 * setup.py: Installation script. See "Installation" below.
147 * install.py: Quick & dirty installation script. Just run it.
149 * docutils: The project source directory, installed as a Python
152 * extras: Directory for third-party modules that Docutils depends on.
153 These are only installed if they're not already present.
155 * docs: The project user documentation directory. Contains the
158 - docs/tools.txt: Docutils Front-End Tools
159 - docs/latex.txt: Docutils LaTeX Writer
160 - docs/rst/quickstart.txt: A ReStructuredText Primer
161 - docs/rst/quickref.html: Quick reStructuredText (HTML only)
163 * licenses: Directory containing copies of license files for
164 non-public-domain files.
166 * spec: The project specification directory. Contains PEPs (Python
167 Enhancement Proposals), XML DTDs (document type definitions), and
168 other documents. The ``spec/rst`` directory contains the
169 reStructuredText specification. The ``spec/howto`` directory
170 contains How-To documents for developers.
172 * tools: Directory for Docutils front-end tools. See docs/tools.txt
175 * test: Unit tests. Not required to use the software, but very useful
176 if you're planning to modify it. See `Running the Test Suite`_
183 The first step is to expand the ``.tar.gz`` or ``.tgz`` archive in a
184 temporary directory (**not** directly in Python's ``site-packages``).
185 It contains a distutils setup file "setup.py". OS-specific
186 installation instructions follow.
189 GNU/Linux, BSDs, Unix, Mac OS X, etc.
190 -------------------------------------
194 2. Go to the directory created by expanding the archive::
196 cd <archive_directory_path>
198 3. Install the package::
200 python setup.py install
202 If the python executable isn't on your path, you'll have to specify
203 the complete path, such as /usr/local/bin/python. You may need
204 root permissions to complete this step.
206 You can also just run install.py; it does the same thing.
212 1. Open a DOS box (Command Shell, MSDOS Prompt, or whatever they're
213 calling it these days).
215 2. Go to the directory created by expanding the archive::
217 cd <archive_directory_path>
219 3. Install the package::
221 <path_to_python.exe>\python setup.py install
223 If your system is set up to run Python when you double-click on .py
224 files, you can run install.py to do the same as the above.
230 1. Open the folder containing the expanded archive.
232 2. Double-click on the file "setup.py", which should be a "Python
235 If the file isn't a "Python module", the line endings are probably
236 also wrong, and you will need to set up your system to recognize
237 ".py" file extensions as Python files. See
238 http://gotools.sourceforge.net/mac/python.html for detailed
239 instructions. Once set up, it's easiest to start over by expanding
242 3. The distutils options window will appear. From the "Command" popup
243 list choose "install", click "Add", then click "OK".
245 If install.py is a "Python module" (see step 2 above if it isn't), you
246 can run it (double-click) instead of the above. The distutils options
247 window will not appear.
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 The final directory name of the ``<archive_directory_path>`` is
260 "docutils" for snapshots. For official releases, the directory may be
261 called "docutils-X.Y", where "X.Y" is the release version.
264 cd <archive_directory_path>
265 tools/buildhtml.py --config=tools/docutils.conf
267 Some files may generate system messages (warnings and errors). The
268 ``tools/test.txt`` file (under the archive directory) contains 5
269 intentional errors. (They test the error reporting mechanism!)
271 There are many front-end tools in the unpacked "tools" subdirectory.
272 You may want to begin with the "rst2html.py" front-end tool. Most
273 tools take up to two arguments, the source path and destination path,
274 with STDIN and STDOUT being the defaults. Use the "--help" option to
275 the front-end tools for details on options and arguments. See
276 `Docutils Front-End Tools`_ (``docs/tools.txt``) for full
279 The package modules are continually growing and evolving. The
280 ``docutils.statemachine`` module is usable independently. It contains
281 extensive inline documentation (in reStructuredText format of course).
283 Contributions are welcome!
285 .. _Docutils Front-End Tools: docs/tools.html
288 Running the Test Suite
289 ======================
291 To run the entire test suite, after installation_ open a shell and use
292 the following commands::
294 cd <archive_directory_path>/test
297 You should see a long line of periods, one for each test, and then a
300 Ran 518 tests in 24.653s
303 Elapsed time: 26.189 seconds
305 The number of tests will grow over time, and the times reported will
306 depend on the computer running the tests. The difference between the
307 two times represents the time required to set up the tests (import
308 modules, create data structures, etc.).
310 If any of the tests fail, please `open a bug report`_ or `send
311 email`_. Please include all relevant output, information about your
312 operating system, Python version, and Docutils version. To see the
313 Docutils version, use these commands::
316 ./quicktest.py --version
318 .. _open a bug report:
319 http://sourceforge.net/tracker/?group_id=38414&atid=422030
320 .. _send email: mailto:docutils-users@lists.sourceforge.net
321 ?subject=Docutils%20test%20suite%20failure
327 If you have questions or need assistance with Docutils or
328 reStructuredText, please `post a message`_ to the `Docutils-Users
331 .. _post a message: mailto:docutils-users@lists.sourceforge.net
332 .. _Docutils-Users mailing list:
333 http://lists.sourceforge.net/lists/listinfo/docutils-users
339 indent-tabs-mode: nil
340 sentence-end-double-space: t