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.
19 1. Docutils requires Python (version 2.3 or later), available from
21 http://www.python.org/
23 See Requirements_ below for details.
25 2. Use the latest Docutils code. Get the code from the `Subversion
26 repository`_ or from the snapshot:
28 http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/docutils/?view=tar
30 See `Releases & Snapshots`_ below for details.
32 3. Unpack the tarball in a temporary directory (**not** directly in
33 Python's ``site-packages``), go to the directory created by expanding
34 the archive, and run ``setup.py install`` with admin rights. On
35 Windows systems it may be sufficient to double-click ``install.py``.
37 See Installation_ below for details.
39 4. Use the front-end scripts to convert reStructuredText documents.
42 rst2html.py FAQ.txt FAQ.html (Unix)
43 python tools/rst2html.py FAQ.txt FAQ.html (Windows)
45 See Usage_ below for details.
51 The purpose of the Docutils project is to create a set of tools for
52 processing plaintext documentation into useful formats, such as HTML,
53 XML, and LaTeX. Support for the following sources has been
58 * `PEPs (Python Enhancement Proposals)`_.
60 Support for the following sources is planned:
62 * Inline documentation from Python modules and packages, extracted
63 with namespace context.
65 * Email (RFC-822 headers, quoted excerpts, signatures, MIME parts).
67 * Wikis, with global reference lookups of "wiki links".
69 * Compound documents, such as multiple chapter files merged into a
72 * And others as discovered.
74 .. _PEPs (Python Enhancement Proposals):
75 http://www.python.org/peps/pep-0012.html
81 While we are trying to follow a "release early & often" policy,
82 features are added very frequently. Since the code in the Subversion
83 repository is usually in a bug-free state, we recommend that you use
84 the current snapshot (which is usually updated within an hour of
85 changes being committed to the repository):
87 * Snapshot of Docutils code, documentation, front-end tools, and
89 http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/docutils/?view=tar
91 * Snapshot of the Sandbox (experimental, contributed code):
92 http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/sandbox/?view=tar
94 To keep up to date on the latest developments, download fresh copies of
95 the snapshots regularly or use a working copy of the
96 `Subversion repository`_.
98 .. _Subversion repository: docs/dev/repository.html
104 To run the code, Python_ must be installed.
105 Docutils is compatible with Python versions from 2.3 up to 2.7 and
106 versions 3.1 and 3.2 (cf. `Python 3 compatibility`_).
108 Docutils uses the following packages for enhanced functionality, if they are
111 * The `Python Imaging Library`_, or PIL, is used for some image
112 manipulation operations.
114 * The `Pygments`_ syntax highlighter is used for content of `code`
115 directives and roles.
117 .. _Python: http://www.python.org/.
118 .. _Python Imaging Library: http://www.pythonware.com/products/pil/
119 .. _Pygments: http://pygments.org/
122 Python 3 compatibility
123 ----------------------
125 The Docutils codebase is written for Python 2 and uses "on-demand"
126 translation for `porting to Python 3`_.
128 * The `setup.py` script generates Python 3 compatible sources in
129 ``build/`` and tests in ``tests3/`` sub-directories during
130 installation_ with Python 3.
132 * The scripts in the ``tools/`` sub-directory work with all supported
133 Python versions without conversion.
135 * To convert the sources without installing (e.g. for testing), run
136 ``python3 setup.py build``.
138 * When editing the source, do changes on the Python 2 versions of the
139 files and re-run the build command.
141 Using Docutils with Python 3.x is less tested and might still have some
144 .. _porting to Python 3: http://docs.python.org/py3k/howto/pyporting.html
147 Project Files & Directories
148 ===========================
150 * README.txt: You're reading it.
152 * COPYING.txt: Public Domain Dedication and copyright details for
153 non-public-domain files (most are PD).
155 * FAQ.txt: Frequently Asked Questions (with answers!).
157 * RELEASE-NOTES.txt: Summary of the major changes in recent releases.
159 * HISTORY.txt: A detailed change log, for the current and all previous
162 * BUGS.txt: Known bugs, and how to report a bug.
164 * THANKS.txt: List of contributors.
166 * setup.py: Installation script. See "Installation" below.
168 * install.py: Quick & dirty installation script. Just run it. For
169 any kind of customization or help though, setup.py must be used.
171 * docutils: The project source directory, installed as a Python
174 * docs: The project documentation directory. Read ``docs/index.txt``
177 * docs/user: The project user documentation directory. Contains the
178 following documents, among others:
180 - docs/user/tools.txt: Docutils Front-End Tools
181 - docs/user/latex.txt: Docutils LaTeX Writer
182 - docs/user/rst/quickstart.txt: A ReStructuredText Primer
183 - docs/user/rst/quickref.html: Quick reStructuredText (HTML only)
185 * docs/ref: The project reference directory.
186 ``docs/ref/rst/restructuredtext.txt`` is the reStructuredText
189 * licenses: Directory containing copies of license files for
190 non-public-domain files.
192 * tools: Directory for Docutils front-end tools. See
193 ``docs/user/tools.txt`` for documentation.
195 * test: Unit tests. Not required to use the software, but very useful
196 if you're planning to modify it. See `Running the Test Suite`_
199 Generated directories when installing under Python 3:
201 * build: Converted sources.
203 * test3: Converted tests.
209 The first step is to expand the ``.tgz`` archive in a temporary
210 directory (**not** directly in Python's ``site-packages``). It
211 contains a distutils setup file "setup.py". OS-specific installation
215 GNU/Linux, BSDs, Unix, Mac OS X, etc.
216 -------------------------------------
220 2. Go to the directory created by expanding the archive::
222 cd <archive_directory_path>
224 3. Install the package (you may need root permissions to complete this
228 (enter admin password)
229 python setup.py install
231 If the python executable isn't on your path, you'll have to specify
232 the complete path, such as ``/usr/local/bin/python``.
234 To install for a specific Python version, use this version in the
237 python3.1 setup.py install
239 To install for different Python versions, repeat step 3 for every
240 required version. The last installed version will be used in the
241 `shebang line`_ of the ``rst2*.py`` wrapper scripts.
243 .. _shebang line: http://en.wikipedia.org/wiki/Shebang_%28Unix%29
248 Just double-click ``install.py``. If this doesn't work, try the
251 1. Open a DOS Box (Command Shell, MS-DOS Prompt, or whatever they're
252 calling it these days).
254 2. Go to the directory created by expanding the archive::
256 cd <archive_directory_path>
258 3. Install the package::
260 <path_to_python.exe>\python setup.py install
262 To install for a specific python version, specify the Python
263 executable for this version.
265 To install for different Python versions, repeat step 3 for every
270 * `running the test suite`_
272 * `converting the documentation`_
278 There are many front-end tools in the unpacked "tools" subdirectory.
279 Installation under Unix places copies in the PATH.
280 You may want to begin with the "rst2html.py" front-end tool. Most
281 tools take up to two arguments, the source path and destination path,
282 with STDIN and STDOUT being the defaults. Use the "--help" option to
283 the front-end tools for details on options and arguments. See
284 Docutils Front-End Tools (``docs/user/tools.txt``) for full documentation.
286 The package modules are continually growing and evolving. The
287 ``docutils.statemachine`` module is usable independently. It contains
288 extensive inline documentation (in reStructuredText format of course).
290 Contributions are welcome!
293 Converting the documentation
294 ============================
296 After unpacking and installing the Docutils package, the following
297 shell commands will generate HTML for all included documentation::
299 cd <archive_directory_path>/tools
302 On Windows systems, type::
304 cd <archive_directory_path>\tools
305 python buildhtml.py ..
307 The final directory name of the ``<archive_directory_path>`` is
308 "docutils" for snapshots. For official releases, the directory may be
309 called "docutils-X.Y.Z", where "X.Y.Z" is the release version.
312 cd <archive_directory_path>
313 tools/buildhtml.py --config=tools/docutils.conf (Unix)
314 python tools\buildhtml.py --config=tools\docutils.conf (Windows)
316 Some files may generate system messages (warnings and errors). The
317 ``docs/user/rst/demo.txt`` file (under the archive directory) contains
318 five intentional errors. (They test the error reporting mechanism!)
321 Running the Test Suite
322 ======================
324 The test suite is documented in `Docutils Testing`_ (docs/dev/testing.txt).
326 To run the entire test suite, open a shell and use the following
329 cd <archive_directory_path>/test
332 Under Windows, type::
334 cd <archive_directory_path>\test
337 For testing with Python 3 use the converted test suite::
339 cd <archive_directory_path>/test3
343 You should see a long line of periods, one for each test, and then a
346 Ran 1111 tests in 24.653s
349 Elapsed time: 26.189 seconds
351 The number of tests will grow over time, and the times reported will
352 depend on the computer running the tests. The difference between the
353 two times represents the time required to set up the tests (import
354 modules, create data structures, etc.).
356 If any of the tests fail, please `open a bug report`_, `send email`_,
357 or post a message via the `web interface`_ (see `Bugs <BUGS.html>`_).
358 Please include all relevant output, information about your operating
359 system, Python version, and Docutils version. To see the Docutils
360 version, use one of the ``rst2*`` front ends or ``tools/quicktest.py``
361 with the ``--version`` option, e.g.::
364 ./quicktest.py --version
366 Windows users type these commands::
369 python quicktest.py --version
372 .. _Docutils Testing: http://docutils.sourceforge.net/docs/dev/testing.html
373 .. _open a bug report:
374 http://sourceforge.net/tracker/?group_id=38414&atid=422030
375 .. _send email: mailto:docutils-users@lists.sourceforge.net
376 ?subject=Test%20suite%20failure
377 .. _web interface: http://post.gmane.org/post.php
378 ?group=gmane.text.docutils.user&subject=Test+suite+failure
384 If you have questions or need assistance with Docutils or
385 reStructuredText, please post a message to the Docutils-users_ mailing
388 .. _Docutils-users: docs/user/mailing-lists.html#docutils-users
394 indent-tabs-mode: nil
395 sentence-end-double-space: t