docutils/README.txt

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