README.txt

   1 ======================
   2  README: Docutils 0.6
   3 ======================
   4
   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.
  10
  11 .. contents::
  12
  13
  14 Quick-Start
  15 ===========
  16
  17 This is for those who want to get up & running quickly.  Read on for
  18 complete details.
  19
  20 1. Get and install the latest release of Python, available from
  21
  22        http://www.python.org/
  23
  24    Docutils is compatible with Python versions from 2.3 up to 2.6.
  25
  26 2. Use the latest Docutils code.  Get the code from Subversion or from
  27    the snapshot:
  28
  29        http://docutils.sf.net/docutils-snapshot.tgz
  30
  31    See `Releases & Snapshots`_ below for details.
  32
  33 3. Unpack the tarball in a temporary directory (**not** directly in
  34    Python's ``site-packages``) and run ``install.py`` with admin
  35    rights.  On Windows systems it may be sufficient to double-click
  36    ``install.py``.  On Unix or Mac OS X, type::
  37
  38         su
  39         (enter admin password)
  40         ./install.py
  41
  42    See Installation_ below for details.
  43
  44 4. Use a front-end tool from the "tools" subdirectory of the same
  45    directory as in step 3.  For example::
  46
  47        cd tools
  48        ./rst2html.py ../FAQ.txt ../FAQ.html        (Unix)
  49        python rst2html.py ..\FAQ.txt ..\FAQ.html   (Windows)
  50
  51    See Usage_ below for details.
  52
  53
  54 Purpose
  55 =======
  56
  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 LaTeX.  Support for the following sources has been
  60 implemented:
  61
  62 * Standalone files.
  63
  64 * `PEPs (Python Enhancement Proposals)`_.
  65
  66 Support for the following sources is planned:
  67
  68 * Inline documentation from Python modules and packages, extracted
  69   with namespace context.
  70
  71 * Email (RFC-822 headers, quoted excerpts, signatures, MIME parts).
  72
  73 * Wikis, with global reference lookups of "wiki links".
  74
  75 * Compound documents, such as multiple chapter files merged into a
  76   book.
  77
  78 * And others as discovered.
  79
  80 .. _PEPs (Python Enhancement Proposals):
  81    http://www.python.org/peps/pep-0012.html
  82
  83
  84 Releases & Snapshots
  85 ====================
  86
  87 While we are trying to follow a "release early & often" policy,
  88 features are added very frequently.  Since the code in the Subversion
  89 repository is usually in a bug-free state, we recommend that you use
  90 the current snapshot (which is usually updated within an hour of
  91 changes being committed to the repository):
  92
  93 * Snapshot of Docutils code, documentation, front-end tools, and
  94   tests: http://docutils.sf.net/docutils-snapshot.tgz
  95
  96 * Snapshot of the Sandbox (experimental, contributed code):
  97   http://docutils.sf.net/docutils-sandbox-snapshot.tgz
  98
  99 To keep up to date on the latest developments, download fresh copies
 100 of the snapshots regularly.  New functionality is being added weekly,
 101 sometimes daily.  (There's also the `Subversion repository`_.)
 102
 103 .. _Subversion repository: docs/dev/repository.html
 104
 105
 106 Requirements
 107 ============
 108
 109 To run the code, Python 2.3 or later must already be installed.
 110 Python is available from
 111 http://www.python.org/.
 112
 113 The `Python Imaging Library`, or PIL, is used for some image
 114 manipulation operations if it is installed.
 115
 116 .. _Python Imaging Library: http://www.pythonware.com/products/pil/
 117 .. _Optik: http://optik.sourceforge.net/
 118
 119
 120 Project Files & Directories
 121 ===========================
 122
 123 * README.txt: You're reading it.
 124
 125 * COPYING.txt: Public Domain Dedication and copyright details for
 126   non-public-domain files (most are PD).
 127
 128 * FAQ.txt: Frequently Asked Questions (with answers!).
 129
 130 * RELEASE-NOTES.txt: Summary of the major changes in recent releases.
 131
 132 * HISTORY.txt: A detailed change log, for the current and all previous
 133   project releases.
 134
 135 * BUGS.txt: Known bugs, and how to report a bug.
 136
 137 * THANKS.txt: List of contributors.
 138
 139 * setup.py: Installation script.  See "Installation" below.
 140
 141 * install.py: Quick & dirty installation script.  Just run it.  For
 142   any kind of customization or help though, setup.py must be used.
 143
 144 * docutils: The project source directory, installed as a Python
 145   package.
 146
 147 * extras: Directory for third-party modules that Docutils depends on
 148   (roman.py).  These are only installed if
 149   they're not already present.
 150
 151 * docs: The project documentation directory.  Read ``docs/index.txt``
 152   for an overview.
 153
 154 * docs/user: The project user documentation directory.  Contains the
 155   following documents, among others:
 156
 157   - docs/user/tools.txt: Docutils Front-End Tools
 158   - docs/user/latex.txt: Docutils LaTeX Writer
 159   - docs/user/rst/quickstart.txt: A ReStructuredText Primer
 160   - docs/user/rst/quickref.html: Quick reStructuredText (HTML only)
 161
 162 * docs/ref: The project reference directory.
 163   ``docs/ref/rst/restructuredtext.txt`` is the reStructuredText
 164   reference.
 165
 166 * licenses: Directory containing copies of license files for
 167   non-public-domain files.
 168
 169 * tools: Directory for Docutils front-end tools.  See
 170   ``docs/user/tools.txt`` for documentation.
 171
 172 * test: Unit tests.  Not required to use the software, but very useful
 173   if you're planning to modify it.  See `Running the Test Suite`_
 174   below.
 175
 176
 177 Installation
 178 ============
 179
 180 The first step is to expand the ``.tgz`` archive in a temporary
 181 directory (**not** directly in Python's ``site-packages``).  It
 182 contains a distutils setup file "setup.py".  OS-specific installation
 183 instructions follow.
 184
 185
 186 GNU/Linux, BSDs, Unix, Mac OS X, etc.
 187 -------------------------------------
 188
 189 1. Open a shell.
 190
 191 2. Go to the directory created by expanding the archive::
 192
 193        cd <archive_directory_path>
 194
 195 3. Install the package::
 196
 197        python setup.py install
 198
 199    If the python executable isn't on your path, you'll have to specify
 200    the complete path, such as /usr/local/bin/python.  You may need
 201    root permissions to complete this step.
 202
 203    You can also just run install.py; it does the same thing.
 204
 205
 206 Windows
 207 -------
 208
 209 Just double-click ``install.py``.  If this doesn't work, try the
 210 following:
 211
 212 1. Open a DOS Box (Command Shell, MS-DOS Prompt, or whatever they're
 213    calling it these days).
 214
 215 2. Go to the directory created by expanding the archive::
 216
 217        cd <archive_directory_path>
 218
 219 3. Install the package::
 220
 221        <path_to_python.exe>\python setup.py install
 222
 223
 224 Usage
 225 =====
 226
 227 After unpacking and installing the Docutils package, the following
 228 shell commands will generate HTML for all included documentation::
 229
 230     cd <archive_directory_path>/tools
 231     ./buildhtml.py ../
 232
 233 On Windows systems, type::
 234
 235     cd <archive_directory_path>\tools
 236     python buildhtml.py ..
 237
 238 The final directory name of the ``<archive_directory_path>`` is
 239 "docutils" for snapshots.  For official releases, the directory may be
 240 called "docutils-X.Y.Z", where "X.Y.Z" is the release version.
 241 Alternatively::
 242
 243     cd <archive_directory_path>
 244     tools/buildhtml.py --config=tools/docutils.conf          (Unix)
 245     python tools\buildhtml.py --config=tools\docutils.conf   (Windows)
 246
 247 Some files may generate system messages (warnings and errors).  The
 248 ``docs/user/rst/demo.txt`` file (under the archive directory) contains
 249 5 intentional errors.  (They test the error reporting mechanism!)
 250
 251 There are many front-end tools in the unpacked "tools" subdirectory.
 252 You may want to begin with the "rst2html.py" front-end tool.  Most
 253 tools take up to two arguments, the source path and destination path,
 254 with STDIN and STDOUT being the defaults.  Use the "--help" option to
 255 the front-end tools for details on options and arguments.  See
 256 Docutils Front-End Tools (``docs/user/tools.txt``) for full documentation.
 257
 258 The package modules are continually growing and evolving.  The
 259 ``docutils.statemachine`` module is usable independently.  It contains
 260 extensive inline documentation (in reStructuredText format of course).
 261
 262 Contributions are welcome!
 263
 264
 265 Running the Test Suite
 266 ======================
 267
 268 To run the entire test suite, after installation_ open a shell and use
 269 the following commands::
 270
 271     cd <archive_directory_path>/test
 272     ./alltests.py
 273
 274 Under Windows, type::
 275
 276     cd <archive_directory_path>\test
 277     python alltests.py
 278
 279 You should see a long line of periods, one for each test, and then a
 280 summary like this::
 281
 282     Ran 518 tests in 24.653s
 283
 284     OK
 285     Elapsed time: 26.189 seconds
 286
 287 The number of tests will grow over time, and the times reported will
 288 depend on the computer running the tests.  The difference between the
 289 two times represents the time required to set up the tests (import
 290 modules, create data structures, etc.).
 291
 292 If any of the tests fail, please `open a bug report`_, `send email`_,
 293 or post a message via the `web interface`_.  Please include all
 294 relevant output, information about your operating system, Python
 295 version, and Docutils version.  To see the Docutils version, use these
 296 commands in the shell::
 297
 298     cd ../tools
 299     ./quicktest.py --version
 300
 301 Windows users type these commands::
 302
 303     cd ..\tools
 304     python quicktest.py --version
 305
 306 .. _open a bug report:
 307    http://sourceforge.net/tracker/?group_id=38414&atid=422030
 308 .. _send email: mailto:docutils-users@lists.sourceforge.net
 309    ?subject=Test%20suite%20failure
 310 .. _web interface: http://post.gmane.org/post.php
 311    ?group=gmane.text.docutils.user&subject=Test+suite+failure
 312
 313
 314 Getting Help
 315 ============
 316
 317 If you have questions or need assistance with Docutils or
 318 reStructuredText, please post a message to the Docutils-users_ mailing
 319 list.
 320
 321 .. _Docutils-users: docs/user/mailing-lists.html#docutils-users
 322
 323 \f
 324 ..
 325    Local Variables:
 326    mode: indented-text
 327    indent-tabs-mode: nil
 328    sentence-end-double-space: t
 329    fill-column: 70
 330    End: