docutils/README.txt

   1 =======================
   2  README: Docutils 0.12
   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.
  18
  19 1. Docutils requires Python (version 2.4 or later), available from
  20
  21      http://www.python.org/
  22
  23    See Requirements_ below for details.
  24
  25 2. Use the latest Docutils code.  Get the code from the `Subversion
  26    repository`_ or from the snapshot:
  27
  28      http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/docutils/?view=tar
  29
  30    See `Releases & Snapshots`_ below for details.
  31
  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``.
  36
  37    See Installation_ below for details.
  38
  39 4. Use the front-end scripts to convert reStructuredText documents.
  40    Try for example::
  41
  42        rst2html.py FAQ.txt FAQ.html         (Unix)
  43        python tools/rst2html.py FAQ.txt FAQ.html  (Windows)
  44
  45    See Usage_ below for details.
  46
  47
  48 Purpose
  49 =======
  50
  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
  54 implemented:
  55
  56 * Standalone files.
  57
  58 * `PEPs (Python Enhancement Proposals)`_.
  59
  60 Support for the following sources is planned:
  61
  62 * Inline documentation from Python modules and packages, extracted
  63   with namespace context.
  64
  65 * Email (RFC-822 headers, quoted excerpts, signatures, MIME parts).
  66
  67 * Wikis, with global reference lookups of "wiki links".
  68
  69 * Compound documents, such as multiple chapter files merged into a
  70   book.
  71
  72 * And others as discovered.
  73
  74 .. _PEPs (Python Enhancement Proposals):
  75    http://www.python.org/peps/pep-0012.html
  76
  77
  78 Releases & Snapshots
  79 ====================
  80
  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):
  86
  87 * Snapshot of Docutils code, documentation, front-end tools, and
  88   tests:
  89   http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/docutils/?view=tar
  90
  91 * Snapshot of the Sandbox (experimental, contributed code):
  92   http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/sandbox/?view=tar
  93
  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`_.
  97
  98 .. _Subversion repository: docs/dev/repository.html
  99
 100
 101 Requirements
 102 ============
 103
 104 To run the code, Python_ must be installed.
 105 Docutils is compatible with Python versions from 2.4 up to 2.7 and
 106 versions 3.1 and 3.2 (cf. `Python 3 compatibility`_).
 107
 108 Docutils uses the following packages for enhanced functionality, if they are
 109 installed:
 110
 111 * The `Python Imaging Library`_, or PIL, is used for some image
 112   manipulation operations.
 113
 114 * The `Pygments`_ syntax highlighter is used for content of `code`
 115   directives and roles.
 116
 117 .. _Python: http://www.python.org/.
 118 .. _Python Imaging Library: http://www.pythonware.com/products/pil/
 119 .. _Pygments: http://pygments.org/
 120
 121
 122 Python 3 compatibility
 123 ----------------------
 124
 125 The Docutils codebase is written for Python 2 and uses "on-demand"
 126 translation for `porting to Python 3`_.
 127
 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.
 131
 132 * The scripts in the ``tools/`` sub-directory work with all supported
 133   Python versions without conversion.
 134
 135 * To convert the sources without installing (e.g. for testing), run
 136   ``python3 setup.py build``.
 137
 138 * When editing the source, do changes on the Python 2 versions of the
 139   files and re-run the build command.
 140
 141 Using Docutils with Python 3.x is less tested and might still have some
 142 issues.
 143
 144 .. _porting to Python 3: http://docs.python.org/py3k/howto/pyporting.html
 145
 146
 147 Project Files & Directories
 148 ===========================
 149
 150 * README.txt: You're reading it.
 151
 152 * COPYING.txt: Public Domain Dedication and copyright details for
 153   non-public-domain files (most are PD).
 154
 155 * FAQ.txt: Frequently Asked Questions (with answers!).
 156
 157 * RELEASE-NOTES.txt: Summary of the major changes in recent releases.
 158
 159 * HISTORY.txt: A detailed change log, for the current and all previous
 160   project releases.
 161
 162 * BUGS.txt: Known bugs, and how to report a bug.
 163
 164 * THANKS.txt: List of contributors.
 165
 166 * setup.py: Installation script.  See "Installation" below.
 167
 168 * install.py: Quick & dirty installation script.  Just run it.  For
 169   any kind of customization or help though, setup.py must be used.
 170
 171 * docutils: The project source directory, installed as a Python
 172   package.
 173
 174 * docs: The project documentation directory.  Read ``docs/index.txt``
 175   for an overview.
 176
 177 * docs/user: The project user documentation directory.  Contains the
 178   following documents, among others:
 179
 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)
 184
 185 * docs/ref: The project reference directory.
 186   ``docs/ref/rst/restructuredtext.txt`` is the reStructuredText
 187   reference.
 188
 189 * licenses: Directory containing copies of license files for
 190   non-public-domain files.
 191
 192 * tools: Directory for Docutils front-end tools.  See
 193   ``docs/user/tools.txt`` for documentation.
 194
 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`_
 197   below.
 198
 199 Generated directories when installing under Python 3:
 200
 201 * build: Converted sources.
 202
 203 * test3: Converted tests.
 204
 205
 206 Installation
 207 ============
 208
 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
 212 instructions follow.
 213
 214
 215 GNU/Linux, BSDs, Unix, Mac OS X, etc.
 216 -------------------------------------
 217
 218 1. Open a shell.
 219
 220 2. Go to the directory created by expanding the archive::
 221
 222        cd <archive_directory_path>
 223
 224 3. Install the package (you may need root permissions to complete this
 225    step)::
 226
 227        su
 228        (enter admin password)
 229        python setup.py install
 230
 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``.
 233
 234    To install for a specific Python version, use this version in the
 235    setup call, e.g. ::
 236
 237        python3.1 setup.py install
 238
 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.
 242
 243    .. _shebang line: http://en.wikipedia.org/wiki/Shebang_%28Unix%29
 244
 245 Windows
 246 -------
 247
 248 Just double-click ``install.py``.  If this doesn't work, try the
 249 following:
 250
 251 1. Open a DOS Box (Command Shell, MS-DOS Prompt, or whatever they're
 252    calling it these days).
 253
 254 2. Go to the directory created by expanding the archive::
 255
 256        cd <archive_directory_path>
 257
 258 3. Install the package::
 259
 260        <path_to_python.exe>\python setup.py install
 261
 262    To install for a specific python version, specify the Python
 263    executable for this version.
 264
 265    To install for different Python versions, repeat step 3 for every
 266    required version.
 267
 268 Optional steps:
 269
 270 * `running the test suite`_
 271
 272 * `converting the documentation`_
 273
 274
 275 Usage
 276 =====
 277
 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.
 285
 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).
 289
 290 Contributions are welcome!
 291
 292
 293 Converting the documentation
 294 ============================
 295
 296 After unpacking and installing the Docutils package, the following
 297 shell commands will generate HTML for all included documentation::
 298
 299     cd <archive_directory_path>/tools
 300     ./buildhtml.py ../
 301
 302 On Windows systems, type::
 303
 304     cd <archive_directory_path>\tools
 305     python buildhtml.py ..
 306
 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.
 310 Alternatively::
 311
 312     cd <archive_directory_path>
 313     tools/buildhtml.py --config=tools/docutils.conf          (Unix)
 314     python tools\buildhtml.py --config=tools\docutils.conf   (Windows)
 315
 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!)
 319
 320
 321 Running the Test Suite
 322 ======================
 323
 324 The test suite is documented in `Docutils Testing`_ (docs/dev/testing.txt).
 325
 326 To run the entire test suite, open a shell and use the following
 327 commands::
 328
 329     cd <archive_directory_path>/test
 330     ./alltests.py
 331
 332 Under Windows, type::
 333
 334     cd <archive_directory_path>\test
 335     python alltests.py
 336
 337 For testing with Python 3 use the converted test suite::
 338
 339     cd <archive_directory_path>/test3
 340     python3 alltests.py
 341
 342
 343 You should see a long line of periods, one for each test, and then a
 344 summary like this::
 345
 346     Ran 1111 tests in 24.653s
 347
 348     OK
 349     Elapsed time: 26.189 seconds
 350
 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.).
 355
 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.::
 362
 363     cd ../tools
 364     ./quicktest.py --version
 365
 366 Windows users type these commands::
 367
 368     cd ..\tools
 369     python quicktest.py --version
 370
 371
 372 .. _Docutils Testing: http://docutils.sourceforge.net/docs/dev/testing.html
 373 .. _open a bug report:
 374    http://sourceforge.net/p/docutils/bugs/
 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
 379
 380
 381 Getting Help
 382 ============
 383
 384 If you have questions or need assistance with Docutils or
 385 reStructuredText, please post a message to the Docutils-users_ mailing
 386 list.
 387
 388 .. _Docutils-users: docs/user/mailing-lists.html#docutils-users
 389
 390 \f
 391 ..
 392    Local Variables:
 393    mode: indented-text
 394    indent-tabs-mode: nil
 395    sentence-end-double-space: t
 396    fill-column: 70
 397    End: