6 :Contact: goodger@users.sourceforge.net
8 :Web site: http://docutils.sourceforge.net/
13 Thank you for downloading the Python Docutils project archive. As
14 this is a work in progress, please check the project website for
15 updated working files (snapshots). This project should be considered
16 highly experimental; APIs are subject to change at any time.
22 This is for those who want to get up & running quickly. Read on for
25 1. Get and install the latest release of Python, available from
27 http://www.python.org/
29 Python 2.2 or later [#py21]_ is required; Python 2.2.2 or later is
32 2. Use the latest Docutils code. Get the code from CVS or from the
35 http://docutils.sf.net/docutils-snapshot.tgz
37 See `Releases & Snapshots`_ below for details.
39 3. Unpack the tarball and install with the standard ::
41 python setup.py install
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 html.py test.txt test.html
51 See Usage_ below for details.
57 The purpose of the Docutils project is to create a set of tools for
58 processing plaintext documentation into useful formats, such as HTML,
59 XML, and TeX. Support for the following sources has been implemented:
63 * `PEPs (Python Enhancement Proposals)`_.
65 Support for the following sources is planned:
67 * Inline documentation from Python modules and packages, extracted
68 with namespace context. **This is the focus of the current
71 * Email (RFC-822 headers, quoted excerpts, signatures, MIME parts).
73 * Wikis, with global reference lookups of "wiki links".
75 * Compound documents, such as multiple chapter files merged into a
78 * And others as discovered.
80 .. _PEPs (Python Enhancement Proposals):
81 http://www.python.org/peps/pep-0012.html
87 Putting together an official "Release" of Docutils is a significant
88 effort, so it isn't done that often. In the meantime, the CVS
89 snapshots always contain the latest code and documentation, usually
90 updated within an hour of changes being committed to the repository,
93 * Snapshot of Docutils code, tests, documentation, and
94 specifications: http://docutils.sf.net/docutils-snapshot.tgz
96 * Snapshot of the Sandbox (experimental, contributed code):
97 http://docutils.sf.net/docutils-sandbox-snapshot.tgz
99 * Snapshot of web files (the files that generate the web site):
100 http://docutils.sf.net/docutils-web-snapshot.tgz
102 To keep up to date on the latest developments, download fresh copies
103 of the snapshots regularly. New functionality is being added weekly,
104 sometimes daily. (There's also the CVS repository, and a mailing list
105 for CVS messages. See the web site [address above] or spec/notes.txt
112 To run the code, Python 2.2 or later [#py21]_ must already be
113 installed. The latest release is recommended (2.2.2 as of this
114 writing). Python is available from http://www.python.org/.
116 .. [#py21] Python 2.1 may be used providing the compiler package is
117 installed. The compiler package can be found in the Tools/
118 directory of Python's source distribution.
121 Project Files & Directories
122 ===========================
124 * README.txt: You're reading it.
126 * COPYING.txt: Copyright details for non-public-domain files (most are
129 * FAQ.txt: Docutils Frequently Asked Questions.
131 * HISTORY.txt: Release notes for the current and previous project
134 * setup.py: Installation script. See "Installation" below.
136 * install.py: Quick & dirty installation script. Just run it.
138 * docutils: The project source directory, installed as a Python
141 * docs: The project user documentation directory. Contains the
144 - docs/tools.txt: Docutils Front-End Tools
145 - docs/rst/quickstart.txt: A ReStructuredText Primer
146 - docs/rst/quickref.html: Quick reStructuredText (HTML only)
148 * spec: The project specification directory. Contains PEPs (Python
149 Enhancement Proposals), XML DTDs (document type definitions), and
150 other documents. The ``spec/rst`` directory contains the
151 reStructuredText specification. The ``spec/howto`` directory
152 contains How-To documents for developers.
154 * tools: Directory for Docutils front-end tools. See docs/tools.txt
157 * test: Unit tests. Not required to use the software, but very useful
158 if you're planning to modify it. See `Running the Test Suite`_
165 The first step is to expand the ``.tar.gz`` or ``.tgz`` archive. It
166 contains a distutils setup file "setup.py". OS-specific installation
170 GNU/Linux, BSDs, Unix, MacOS X, etc.
171 ------------------------------------
175 2. Go to the directory created by expanding the archive::
177 cd <archive_directory_path>
179 3. Install the package::
181 python setup.py install
183 If the python executable isn't on your path, you'll have to specify
184 the complete path, such as /usr/local/bin/python. You may need
185 root permissions to complete this step.
187 You can also just run install.py; it does the same thing.
193 1. Open a DOS box (Command Shell, MSDOS Prompt, or whatever they're
194 calling it these days).
196 2. Go to the directory created by expanding the archive::
198 cd <archive_directory_path>
200 3. Install the package::
202 <path_to_python.exe>\python setup.py install
204 If your system is set up to run Python when you double-click on .py
205 files, you can run install.py to do the same as the above.
211 1. Open the folder containing the expanded archive.
213 2. Double-click on the file "setup.py", which should be a "Python
216 If the file isn't a "Python module", the line endings are probably
217 also wrong, and you will need to set up your system to recognize
218 ".py" file extensions as Python files. See
219 http://gotools.sourceforge.net/mac/python.html for detailed
220 instructions. Once set up, it's easiest to start over by expanding
223 3. The distutils options window will appear. From the "Command" popup
224 list choose "install", click "Add", then click "OK".
226 If install.py is a "Python module" (see step 2 above if it isn't), you
227 can run it instead of the above. The distutils options window will
234 After unpacking and installing the Docutils package, the following
235 shell commands will generate HTML for all included documentation::
237 cd <archive_directory_path>/tools
240 The final directory name of the ``<archive_directory_path>`` is
241 "docutils" for snapshots. For official releases, the directory may be
242 called "docutils-X.Y", where "X.Y" is the release version.
245 cd <archive_directory_path>
246 tools/buildhtml.py --config=tools/docutils.conf
248 Some files may generate system messages (warnings and errors). The
249 ``tools/test.txt`` file (under the archive directory) contains 5
250 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 "html.py" front-end tool. Most tools
254 take up to two arguments, the source path and destination path, with
255 STDIN and STDOUT being the defaults. Use the "--help" option to the
256 front-end tools for details on options and arguments. See `Docutils
257 Front-End Tools`_ (``docs/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!
265 .. _Docutils Front-End Tools: docs/tools.html
268 Running the Test Suite
269 ======================
271 To run the entire test suite, after installation_ open a shell and use
272 the following commands::
274 cd <archive_directory_path>/test
277 You should see a long line of periods, one for each test, and then a
280 Ran 518 tests in 24.653s
283 Elapsed time: 26.189 seconds
285 The number of tests will grow over time, and the times reported will
286 depend on the computer running the tests. The difference between the
287 two times represents the time required to set up the tests (import
288 modules, create data structures, etc.).
290 If any of the tests fail, please `open a bug report`_ or `send
291 email`_. Please include all relevant output, information about your
292 operating system, Python version, and Docutils version. To see the
293 Docutils version, use these commands::
296 ./quicktest.py --version
298 .. _open a bug report:
299 http://sourceforge.net/tracker/?group_id=38414&atid=422030
300 .. _send email: mailto:docutils-users@lists.sourceforge.net
301 ?subject=Docutils%20test%20suite%20failure
307 If you have questions or need assistance with Docutils or
308 reStructuredText, please `post a message`_ to the `Docutils-Users
311 .. _post a message: mailto:docutils-users@lists.sourceforge.net
312 .. _Docutils-Users mailing list:
313 http://lists.sourceforge.net/lists/listinfo/docutils-users
319 indent-tabs-mode: nil
320 sentence-end-double-space: t