docutils/README.txt

   1 ============================
   2  README: Docutils 0.15b.dev
   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.6 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``. 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 frequently.  Since the code in the Subversion
  83 repository is usually in a bug-free state, we recommend that you use
  84 a current snapshot.
  85
  86 To get a snapshot, go to the code page and click the download snapshot
  87 button:
  88
  89 * Docutils code, documentation, front-end tools, and tests:
  90   https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/
  91
  92 * Sandbox (experimental, contributed code):
  93   https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/sandbox/
  94
  95 To keep up to date on the latest developments, download fresh copies of
  96 the snapshots regularly or use a working copy of the
  97 `Subversion repository`_.
  98
  99 .. _Subversion repository: docs/dev/repository.html
 100
 101
 102 Requirements
 103 ============
 104
 105 To run the code, Python_ must be installed.
 106 Docutils is compatible with Python versions 2.6, 2.7, and
 107 versions 3.3 to 3.5 (cf. `Python 3 compatibility`_).
 108
 109 Docutils uses the following packages for enhanced functionality, if they are
 110 installed:
 111
 112 * The `Python Imaging Library`_, or PIL, is used for some image
 113   manipulation operations.
 114
 115 * The `Pygments`_ syntax highlighter is used for content of `code`
 116   directives and roles.
 117
 118 .. _Python: http://www.python.org/.
 119 .. _Python Imaging Library: http://www.pythonware.com/products/pil/
 120 .. _Pygments: http://pygments.org/
 121
 122
 123 Python 3 compatibility
 124 ----------------------
 125
 126 The Docutils codebase is written for Python 2 and uses "on-demand"
 127 translation for `porting to Python 3`_.
 128
 129 * The `setup.py` script generates Python 3 compatible sources in
 130   ``build/`` and tests in ``tests3/`` sub-directories during
 131   installation_ with Python 3.
 132
 133 * The scripts in the ``tools/`` sub-directory work with all supported
 134   Python versions without conversion.
 135
 136 * To convert the sources without installing (e.g. for testing), run
 137   ``python3 setup.py build``.
 138
 139 * When editing the source, do changes on the Python 2 versions of the
 140   files and re-run the build command.
 141
 142 .. _porting to Python 3: http://docs.python.org/py3k/howto/pyporting.html
 143
 144
 145 Project Files & Directories
 146 ===========================
 147
 148 * README.txt: You're reading it.
 149
 150 * COPYING.txt: Public Domain Dedication and copyright details for
 151   non-public-domain files (most are PD).
 152
 153 * FAQ.txt: Frequently Asked Questions (with answers!).
 154
 155 * RELEASE-NOTES.txt: Summary of the major changes in recent releases.
 156
 157 * HISTORY.txt: A detailed change log, for the current and all previous
 158   project releases.
 159
 160 * BUGS.txt: Known bugs, and how to report a bug.
 161
 162 * THANKS.txt: List of contributors.
 163
 164 * setup.py: Installation script.  See "Installation" below.
 165
 166 * install.py: Quick & dirty installation script.  Just run it.  For
 167   any kind of customization or help though, setup.py must be used.
 168
 169 * docutils: The project source directory, installed as a Python
 170   package.
 171
 172 * docs: The project documentation directory.  Read ``docs/index.txt``
 173   for an overview.
 174
 175 * docs/user: The project user documentation directory.  Contains the
 176   following documents, among others:
 177
 178   - docs/user/tools.txt: Docutils Front-End Tools
 179   - docs/user/latex.txt: Docutils LaTeX Writer
 180   - docs/user/rst/quickstart.txt: A ReStructuredText Primer
 181   - docs/user/rst/quickref.html: Quick reStructuredText (HTML only)
 182
 183 * docs/ref: The project reference directory.
 184   ``docs/ref/rst/restructuredtext.txt`` is the reStructuredText
 185   reference.
 186
 187 * licenses: Directory containing copies of license files for
 188   non-public-domain files.
 189
 190 * tools: Directory for Docutils front-end tools.  See
 191   ``docs/user/tools.txt`` for documentation.
 192
 193 * test: Unit tests.  Not required to use the software, but very useful
 194   if you're planning to modify it.  See `Running the Test Suite`_
 195   below.
 196
 197 Generated directories when installing under Python 3:
 198
 199 * build: Converted sources.
 200
 201 * test3: Converted tests.
 202
 203
 204 Installation
 205 ============
 206
 207 The first step is to expand the ``.tgz`` archive in a temporary
 208 directory (**not** directly in Python's ``site-packages``).  It
 209 contains a distutils setup file "setup.py".  OS-specific installation
 210 instructions follow.
 211
 212
 213 GNU/Linux, BSDs, Unix, Mac OS X, etc.
 214 -------------------------------------
 215
 216 1. Open a shell.
 217
 218 2. Go to the directory created by expanding the archive::
 219
 220        cd <archive_directory_path>
 221
 222 3. Install the package (you may need root permissions to complete this
 223    step)::
 224
 225        su
 226        (enter admin password)
 227        python setup.py install
 228
 229    If the python executable isn't on your path, you'll have to specify
 230    the complete path, such as ``/usr/local/bin/python``.
 231
 232    To install for a specific Python version, use this version in the
 233    setup call, e.g. ::
 234
 235        python3.1 setup.py install
 236
 237    To install for different Python versions, repeat step 3 for every
 238    required version. The last installed version will be used in the
 239    `shebang line`_ of the ``rst2*.py`` wrapper scripts.
 240
 241    .. _shebang line: http://en.wikipedia.org/wiki/Shebang_%28Unix%29
 242
 243 Windows
 244 -------
 245
 246 Just double-click ``install.py``.  If this doesn't work, try the
 247 following:
 248
 249 1. Open a DOS Box (Command Shell, MS-DOS Prompt, or whatever they're
 250    calling it these days).
 251
 252 2. Go to the directory created by expanding the archive::
 253
 254        cd <archive_directory_path>
 255
 256 3. Install the package::
 257
 258        <path_to_python.exe>\python setup.py install
 259
 260    To install for a specific python version, specify the Python
 261    executable for this version.
 262
 263    To install for different Python versions, repeat step 3 for every
 264    required version.
 265
 266 Optional steps:
 267
 268 * `running the test suite`_
 269
 270 * `converting the documentation`_
 271
 272
 273 Usage
 274 =====
 275
 276 There are many front-end tools in the unpacked "tools" subdirectory.
 277 Installation under Unix places copies in the PATH.
 278 You may want to begin with the "rst2html.py" front-end tool.  Most
 279 tools take up to two arguments, the source path and destination path,
 280 with STDIN and STDOUT being the defaults.  Use the "--help" option to
 281 the front-end tools for details on options and arguments.  See
 282 Docutils Front-End Tools (``docs/user/tools.txt``) for full documentation.
 283
 284 The package modules are continually growing and evolving.  The
 285 ``docutils.statemachine`` module is usable independently.  It contains
 286 extensive inline documentation (in reStructuredText format of course).
 287
 288 Contributions are welcome!
 289
 290
 291 Converting the documentation
 292 ============================
 293
 294 After unpacking and installing the Docutils package, the following
 295 shell commands will generate HTML for all included documentation::
 296
 297     cd <archive_directory_path>/tools
 298     ./buildhtml.py ../
 299
 300 On Windows systems, type::
 301
 302     cd <archive_directory_path>\tools
 303     python buildhtml.py ..
 304
 305 The final directory name of the ``<archive_directory_path>`` is
 306 "docutils" for snapshots.  For official releases, the directory may be
 307 called "docutils-X.Y.Z", where "X.Y.Z" is the release version.
 308 Alternatively::
 309
 310     cd <archive_directory_path>
 311     tools/buildhtml.py --config=tools/docutils.conf          (Unix)
 312     python tools\buildhtml.py --config=tools\docutils.conf   (Windows)
 313
 314 Some files may generate system messages (warnings and errors).  The
 315 ``docs/user/rst/demo.txt`` file (under the archive directory) contains
 316 five intentional errors.  (They test the error reporting mechanism!)
 317
 318
 319 Running the Test Suite
 320 ======================
 321
 322 The test suite is documented in `Docutils Testing`_ (docs/dev/testing.txt).
 323
 324 To run the entire test suite, open a shell and use the following
 325 commands::
 326
 327     cd <archive_directory_path>/test
 328     ./alltests.py
 329
 330 Under Windows, type::
 331
 332     cd <archive_directory_path>\test
 333     python alltests.py
 334
 335 For testing with Python 3 use the converted test suite::
 336
 337     cd <archive_directory_path>/test3
 338     python3 alltests.py
 339
 340
 341 You should see a long line of periods, one for each test, and then a
 342 summary like this::
 343
 344     Ran 1111 tests in 24.653s
 345
 346     OK
 347     Elapsed time: 26.189 seconds
 348
 349 The number of tests will grow over time, and the times reported will
 350 depend on the computer running the tests.  The difference between the
 351 two times represents the time required to set up the tests (import
 352 modules, create data structures, etc.).
 353
 354 If any of the tests fail, please `open a bug report`_ or `send an email`_
 355 (see `Bugs <BUGS.html>`_).
 356 Please include all relevant output, information about your operating
 357 system, Python version, and Docutils version.  To see the Docutils
 358 version, use one of the ``rst2*`` front ends or ``tools/quicktest.py``
 359 with the ``--version`` option, e.g.::
 360
 361     cd ../tools
 362     ./quicktest.py --version
 363
 364 Windows users type these commands::
 365
 366     cd ..\tools
 367     python quicktest.py --version
 368
 369
 370 .. _Docutils Testing: http://docutils.sourceforge.net/docs/dev/testing.html
 371 .. _open a bug report:
 372    http://sourceforge.net/p/docutils/bugs/
 373 .. _send an email: mailto:docutils-users@lists.sourceforge.net
 374    ?subject=Test%20suite%20failure
 375 .. _web interface: https://sourceforge.net/p/docutils/mailman/
 376
 377
 378 Getting Help
 379 ============
 380
 381 If you have questions or need assistance with Docutils or
 382 reStructuredText, please post a message to the Docutils-users_ mailing
 383 list.
 384
 385 .. _Docutils-users: docs/user/mailing-lists.html#docutils-users
 386
 387 \f
 388 ..
 389    Local Variables:
 390    mode: indented-text
 391    indent-tabs-mode: nil
 392    sentence-end-double-space: t
 393    fill-column: 70
 394    End: