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 .. [#py21] Python 2.1 may be used providing the compiler package is
119 installed. The compiler package can be found in the Tools/
120 directory of Python 2.1's source distribution.
123 Project Files & Directories
124 ===========================
126 * README.txt: You're reading it.
128 * COPYING.txt: Public Domain Dedication and copyright details for
129 non-public-domain files (most are PD).
131 * FAQ.txt: Docutils Frequently Asked Questions.
133 * HISTORY.txt: Release notes for the current and previous project
136 * setup.py: Installation script. See "Installation" below.
138 * install.py: Quick & dirty installation script. Just run it.
140 * docutils: The project source directory, installed as a Python
143 * extras: Directory for third-party modules that Docutils depends on.
144 These are only installed if they're not already present.
146 * docs: The project user documentation directory. Contains the
149 - docs/tools.txt: Docutils Front-End Tools
150 - docs/latex.txt: Docutils LaTeX Writer
151 - docs/rst/quickstart.txt: A ReStructuredText Primer
152 - docs/rst/quickref.html: Quick reStructuredText (HTML only)
154 * licenses: Directory containing copies of license files for
155 non-public-domain files.
157 * spec: The project specification directory. Contains PEPs (Python
158 Enhancement Proposals), XML DTDs (document type definitions), and
159 other documents. The ``spec/rst`` directory contains the
160 reStructuredText specification. The ``spec/howto`` directory
161 contains How-To documents for developers.
163 * tools: Directory for Docutils front-end tools. See docs/tools.txt
166 * test: Unit tests. Not required to use the software, but very useful
167 if you're planning to modify it. See `Running the Test Suite`_
174 The first step is to expand the ``.tar.gz`` or ``.tgz`` archive in a
175 temporary directory (**not** directly in Python's ``site-packages``).
176 It contains a distutils setup file "setup.py". OS-specific
177 installation instructions follow.
180 GNU/Linux, BSDs, Unix, Mac OS X, etc.
181 -------------------------------------
185 2. Go to the directory created by expanding the archive::
187 cd <archive_directory_path>
189 3. Install the package::
191 python setup.py install
193 If the python executable isn't on your path, you'll have to specify
194 the complete path, such as /usr/local/bin/python. You may need
195 root permissions to complete this step.
197 You can also just run install.py; it does the same thing.
203 1. Open a DOS box (Command Shell, MSDOS Prompt, or whatever they're
204 calling it these days).
206 2. Go to the directory created by expanding the archive::
208 cd <archive_directory_path>
210 3. Install the package::
212 <path_to_python.exe>\python setup.py install
214 If your system is set up to run Python when you double-click on .py
215 files, you can run install.py to do the same as the above.
221 1. Open the folder containing the expanded archive.
223 2. Double-click on the file "setup.py", which should be a "Python
226 If the file isn't a "Python module", the line endings are probably
227 also wrong, and you will need to set up your system to recognize
228 ".py" file extensions as Python files. See
229 http://gotools.sourceforge.net/mac/python.html for detailed
230 instructions. Once set up, it's easiest to start over by expanding
233 3. The distutils options window will appear. From the "Command" popup
234 list choose "install", click "Add", then click "OK".
236 If install.py is a "Python module" (see step 2 above if it isn't), you
237 can run it (double-click) instead of the above. The distutils options
238 window will not appear.
244 After unpacking and installing the Docutils package, the following
245 shell commands will generate HTML for all included documentation::
247 cd <archive_directory_path>/tools
250 The final directory name of the ``<archive_directory_path>`` is
251 "docutils" for snapshots. For official releases, the directory may be
252 called "docutils-X.Y", where "X.Y" is the release version.
255 cd <archive_directory_path>
256 tools/buildhtml.py --config=tools/docutils.conf
258 Some files may generate system messages (warnings and errors). The
259 ``tools/test.txt`` file (under the archive directory) contains 5
260 intentional errors. (They test the error reporting mechanism!)
262 There are many front-end tools in the unpacked "tools" subdirectory.
263 You may want to begin with the "rst2html.py" front-end tool. Most
264 tools take up to two arguments, the source path and destination path,
265 with STDIN and STDOUT being the defaults. Use the "--help" option to
266 the front-end tools for details on options and arguments. See
267 `Docutils Front-End Tools`_ (``docs/tools.txt``) for full
270 The package modules are continually growing and evolving. The
271 ``docutils.statemachine`` module is usable independently. It contains
272 extensive inline documentation (in reStructuredText format of course).
274 Contributions are welcome!
276 .. _Docutils Front-End Tools: docs/tools.html
279 Running the Test Suite
280 ======================
282 To run the entire test suite, after installation_ open a shell and use
283 the following commands::
285 cd <archive_directory_path>/test
288 You should see a long line of periods, one for each test, and then a
291 Ran 518 tests in 24.653s
294 Elapsed time: 26.189 seconds
296 The number of tests will grow over time, and the times reported will
297 depend on the computer running the tests. The difference between the
298 two times represents the time required to set up the tests (import
299 modules, create data structures, etc.).
301 If any of the tests fail, please `open a bug report`_ or `send
302 email`_. Please include all relevant output, information about your
303 operating system, Python version, and Docutils version. To see the
304 Docutils version, use these commands::
307 ./quicktest.py --version
309 .. _open a bug report:
310 http://sourceforge.net/tracker/?group_id=38414&atid=422030
311 .. _send email: mailto:docutils-users@lists.sourceforge.net
312 ?subject=Docutils%20test%20suite%20failure
318 If you have questions or need assistance with Docutils or
319 reStructuredText, please `post a message`_ to the `Docutils-Users
322 .. _post a message: mailto:docutils-users@lists.sourceforge.net
323 .. _Docutils-Users mailing list:
324 http://lists.sourceforge.net/lists/listinfo/docutils-users
330 indent-tabs-mode: nil
331 sentence-end-double-space: t