Fixes to wrapping of images and figures
[docutils.git] / README.txt
blobfeb4f3edb052a5a349aaeda15020eb1f0684b6ad
1 ==================
2  README: Docutils
3 ==================
5 :Author: David Goodger
6 :Contact: goodger@python.org
7 :Date: $Date$
8 :Web site: http://docutils.sourceforge.net/
9 :Copyright: This document has been placed in the public domain.
11 .. contents::
14 Quick-Start
15 ===========
17 This is for those who want to get up & running quickly.  Read on for
18 complete details.
20 1. Get and install the latest release of Python, available from
22        http://www.python.org/
24    Python 2.2 or later [1]_ is required; Python 2.2.2 or later is
25    recommended.
27 2. Use the latest Docutils code.  Get the code from Subversion or from
28    the snapshot:
30        http://docutils.sf.net/docutils-snapshot.tgz
32    See `Releases & Snapshots`_ below for details.
34 3. Unpack the tarball in a temporary directory (**not** directly in
35    Python's ``site-packages``) and run ``install.py`` with admin
36    rights.  On Windows systems it may be sufficient to double-click
37    ``install.py``.  On Unix or Mac OS X, type::
39         su
40         (enter admin password)
41         ./install.py
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::
48        cd tools
49        ./rst2html.py ../FAQ.txt ../FAQ.html        (Unix)
50        python rst2html.py ..\FAQ.txt ..\FAQ.html   (Windows)
52    See Usage_ below for details.
55 Purpose
56 =======
58 The purpose of the Docutils project is to create a set of tools for
59 processing plaintext documentation into useful formats, such as HTML,
60 XML, and LaTeX.  Support for the following sources has been
61 implemented:
63 * Standalone files.
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.
72 * Email (RFC-822 headers, quoted excerpts, signatures, MIME parts).
74 * Wikis, with global reference lookups of "wiki links".
76 * Compound documents, such as multiple chapter files merged into a
77   book.
79 * And others as discovered.
81 .. _PEPs (Python Enhancement Proposals):
82    http://www.python.org/peps/pep-0012.html
85 Releases & Snapshots
86 ====================
88 While we are trying to follow a "release early & often" policy,
89 features are added very frequently.  Since the code in the Subversion
90 repository is usually in a bug-free state, we recommend that you use
91 the current snapshot (which is usually updated within an hour of
92 changes being committed to the repository):
94 * Snapshot of Docutils code, documentation, front-end tools, and
95   tests: http://docutils.sf.net/docutils-snapshot.tgz
97 * Snapshot of the Sandbox (experimental, contributed code):
98   http://docutils.sf.net/docutils-sandbox-snapshot.tgz
100 To keep up to date on the latest developments, download fresh copies
101 of the snapshots regularly.  New functionality is being added weekly,
102 sometimes daily.  (There's also the `Subversion repository`_.)
104 .. _Subversion repository: docs/dev/repository.html
107 Requirements
108 ============
110 To run the code, Python 2.2 or later [1]_ must already be installed.
111 The latest release is recommended.  Python is available from
112 http://www.python.org/.
114 The `Python Imaging Library`, or PIL, is used for some image
115 manipulation operations if it is installed.
117 .. [1] Python 2.1 may be used providing the compiler package is
118    installed.  The compiler package can be found in the Tools/
119    directory of Python 2.1's source distribution.
121 .. _Python Imaging Library: http://www.pythonware.com/products/pil/
122 .. _Optik: http://optik.sourceforge.net/
125 Project Files & Directories
126 ===========================
128 * README.txt: You're reading it.
130 * COPYING.txt: Public Domain Dedication and copyright details for
131   non-public-domain files (most are PD).
133 * FAQ.txt: Frequently Asked Questions (with answers!).
135 * RELEASE-NOTES.txt: Summary of the major changes in recent releases.
137 * HISTORY.txt: A detailed change log, for the current and all previous
138   project releases.
140 * BUGS.txt: Known bugs, and how to report a bug.
142 * THANKS.txt: List of contributors.
144 * setup.py: Installation script.  See "Installation" below.
146 * install.py: Quick & dirty installation script.  Just run it.  For
147   any kind of customization or help though, setup.py must be used.
149 * docutils: The project source directory, installed as a Python
150   package.
152 * extras: Directory for third-party modules that Docutils depends on
153   (roman.py, optparse.py, textwrap.py).  These are only installed if
154   they're not already present.
156 * docs: The project documentation directory.  Read ``docs/index.txt``
157   for an overview.
159 * docs/user: The project user documentation directory.  Contains the
160   following documents, among others:
162   - docs/user/tools.txt: Docutils Front-End Tools
163   - docs/user/latex.txt: Docutils LaTeX Writer
164   - docs/user/rst/quickstart.txt: A ReStructuredText Primer
165   - docs/user/rst/quickref.html: Quick reStructuredText (HTML only)
167 * docs/ref: The project reference directory.
168   ``docs/ref/rst/restructuredtext.txt`` is the reStructuredText
169   reference.
171 * licenses: Directory containing copies of license files for
172   non-public-domain files.
174 * tools: Directory for Docutils front-end tools.  See
175   ``docs/user/tools.txt`` for documentation.
177 * test: Unit tests.  Not required to use the software, but very useful
178   if you're planning to modify it.  See `Running the Test Suite`_
179   below.
182 Installation
183 ============
185 The first step is to expand the ``.tgz`` archive in a temporary
186 directory (**not** directly in Python's ``site-packages``).  It
187 contains a distutils setup file "setup.py".  OS-specific installation
188 instructions follow.
191 GNU/Linux, BSDs, Unix, Mac OS X, etc.
192 -------------------------------------
194 1. Open a shell.
196 2. Go to the directory created by expanding the archive::
198        cd <archive_directory_path>
200 3. Install the package::
202        python setup.py install
204    If the python executable isn't on your path, you'll have to specify
205    the complete path, such as /usr/local/bin/python.  You may need
206    root permissions to complete this step.
208    You can also just run install.py; it does the same thing.
211 Windows
212 -------
214 Just double-click ``install.py``.  If this doesn't work, try the
215 following:
217 1. Open a DOS Box (Command Shell, MS-DOS 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
229 Usage
230 =====
232 After unpacking and installing the Docutils package, the following
233 shell commands will generate HTML for all included documentation::
235     cd <archive_directory_path>/tools
236     ./buildhtml.py ../
238 On Windows systems, type::
240     cd <archive_directory_path>\tools
241     python buildhtml.py ..
243 The final directory name of the ``<archive_directory_path>`` is
244 "docutils" for snapshots.  For official releases, the directory may be
245 called "docutils-X.Y.Z", where "X.Y.Z" is the release version.
246 Alternatively::
248     cd <archive_directory_path>
249     tools/buildhtml.py --config=tools/docutils.conf          (Unix)
250     python tools\buildhtml.py --config=tools\docutils.conf   (Windows)
252 Some files may generate system messages (warnings and errors).  The
253 ``docs/user/rst/demo.txt`` file (under the archive directory) contains
254 5 intentional errors.  (They test the error reporting mechanism!)
256 There are many front-end tools in the unpacked "tools" subdirectory.
257 You may want to begin with the "rst2html.py" front-end tool.  Most
258 tools take up to two arguments, the source path and destination path,
259 with STDIN and STDOUT being the defaults.  Use the "--help" option to
260 the front-end tools for details on options and arguments.  See
261 Docutils Front-End Tools (``docs/user/tools.txt``) for full documentation.
263 The package modules are continually growing and evolving.  The
264 ``docutils.statemachine`` module is usable independently.  It contains
265 extensive inline documentation (in reStructuredText format of course).
267 Contributions are welcome!
270 Running the Test Suite
271 ======================
273 To run the entire test suite, after installation_ open a shell and use
274 the following commands::
276     cd <archive_directory_path>/test
277     ./alltests.py
279 Under Windows, type::
281     cd <archive_directory_path>\test
282     python alltests.py
284 You should see a long line of periods, one for each test, and then a
285 summary like this::
287     Ran 518 tests in 24.653s
289     OK
290     Elapsed time: 26.189 seconds
292 The number of tests will grow over time, and the times reported will
293 depend on the computer running the tests.  The difference between the
294 two times represents the time required to set up the tests (import
295 modules, create data structures, etc.).
297 If any of the tests fail, please `open a bug report`_, `send email`_,
298 or post a message via the `web interface`_.  Please include all
299 relevant output, information about your operating system, Python
300 version, and Docutils version.  To see the Docutils version, use these
301 commands in the shell::
303     cd ../tools
304     ./quicktest.py --version
306 Windows users type these commands::
308     cd ..\tools
309     python quicktest.py --version
311 .. _open a bug report:
312    http://sourceforge.net/tracker/?group_id=38414&atid=422030
313 .. _send email: mailto:docutils-users@lists.sourceforge.net
314    ?subject=Test%20suite%20failure
315 .. _web interface: http://post.gmane.org/post.php
316    ?group=gmane.text.docutils.user&subject=Test+suite+failure
319 Getting Help
320 ============
322 If you have questions or need assistance with Docutils or
323 reStructuredText, please post a message to the Docutils-users_ mailing
324 list.
326 .. _Docutils-users: docs/user/mailing-lists.html#docutils-users
330    Local Variables:
331    mode: indented-text
332    indent-tabs-mode: nil
333    sentence-end-double-space: t
334    fill-column: 70
335    End: