docutils/README.txt

   1 ==============================
   2  README: Docutils 0.19.1b.dev
   3 ==============================
   4
   5 :Author: David Goodger
   6 :Contact: goodger@python.org
   7 :Date: $Date$
   8 :Web site: https://docutils.sourceforge.io/
   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    https://www.python.org/.
  21    See Dependencies_ below for details.
  22
  23 2. Install the latest stable release from PyPi with pip_::
  24
  25        python3 -m pip install docutils
  26
  27    For alternatives and details, see section `Installation`_ below.
  28
  29 3. Use the `front-end scripts`_ to convert reStructuredText documents.
  30    Try for example::
  31
  32        rst2html.py FAQ.txt FAQ.html         (Unix)
  33        python tools/rst2html.py FAQ.txt FAQ.html  (Windows)
  34
  35    See Usage_ below for details.
  36
  37
  38 Purpose
  39 =======
  40
  41 The purpose of the Docutils project is to create a set of tools for
  42 processing plaintext documentation into useful formats, such as HTML,
  43 LaTeX, troff (man pages), OpenOffice, and native XML.  Support for the
  44 following sources has been implemented:
  45
  46 * Standalone files.
  47
  48 * `PEPs (Python Enhancement Proposals)`_.
  49
  50 Support for the following sources is planned:
  51
  52 * Inline documentation from Python modules and packages, extracted
  53   with namespace context.
  54
  55 * Email (RFC-822 headers, quoted excerpts, signatures, MIME parts).
  56
  57 * Wikis, with global reference lookups of "wiki links".
  58
  59 * Compound documents, such as multiple chapter files merged into a
  60   book.
  61
  62 * And others as discovered.
  63
  64 .. _PEPs (Python Enhancement Proposals):
  65    https://peps.python.org/pep-0012
  66
  67
  68 Dependencies
  69 ============
  70
  71 To run the code, Python_ must be installed.
  72 (Python is pre-installed with most Linux distributions.)
  73
  74 * Docutils 0.19.1b.dev requires Python 3.7 or later.
  75 * Docutils 0.16 to 0.18 require Python 2.7 or 3.5+.
  76 * Docutils 0.14 dropped Python 2.4, 2.5, 3.1 and 3.2 support.
  77
  78 .. _Python: https://www.python.org/.
  79
  80
  81 Optional Dependencies
  82 ---------------------
  83
  84 Docutils uses the following packages for enhanced functionality, if they
  85 are installed:
  86
  87 * Installation_ is usually done with pip_ or setuptools_.
  88
  89 * The `Python Imaging Library`_, or PIL, is used for some image
  90   manipulation operations.
  91
  92 * The `Pygments`_ package provides syntax highlight of "code" directives
  93   and roles.
  94
  95 * The `myst`_ or `recommonmark`_ parsers can be used to parse input in
  96   Markdown format.
  97
  98 The `Docutils Link List <docs/user/links.html>`__ records projects that
  99 users of Docutils and reStructuredText may find useful.
 100
 101 .. _pip: https://pypi.org/project/pip/
 102 .. _setuptools: https://pypi.org/project/setuptools/
 103 .. _Python Imaging Library: http://www.pythonware.com/products/pil/
 104 .. _Pygments: https://pypi.org/project/Pygments/
 105 .. _myst: https://pypi.org/project/myst-docutils/
 106 .. _recommonmark: https://github.com/rtfd/recommonmark
 107
 108
 109 Development version
 110 ===================
 111
 112 While we are trying to follow a "release early & often" policy,
 113 features are added frequently.
 114 Since the code in the `Docutils version repository`_ is usually in a
 115 bug-free state, we recommend using a current snapshot or a working copy.
 116
 117 Snapshots:
 118   To get a repository _`snapshot`, go to
 119   https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/
 120   and click the download snapshot button.
 121
 122 Repository check-out:
 123   To keep up to date on the latest developments,
 124   use a `working copy`__ of the `Docutils version repository`_.
 125
 126 Continue with the `Installation`_ instructions below.
 127
 128 .. _Docutils version repository: docs/dev/repository.html
 129 .. _sandbox: https://docutils.sourceforge.io/sandbox/README.html
 130
 131 __ docs/dev/repository.html#checking-out-the-repository
 132
 133
 134 Installation
 135 ============
 136
 137 * The simplest way is to install the latest stable release from PyPi with
 138   pip_::
 139
 140     python3 -m pip install docutils
 141
 142   To install a pre-relase, append the option ``--pre``.
 143
 144 * To install a `development version`_ from source with `setuptools`_:
 145
 146   * Go to the directory containing the file ``setup.py``.
 147
 148     A snapshot_ must be unpacked in a temporary directory
 149     (**not** directly in Python's ``site-packages``) first.
 150
 151   * Run ``setup.py install``.
 152     See also OS-specific installation instructions below.
 153
 154 * For installing "by hand" or in "development mode", see the
 155   `editable installs`_ section in the `Docutils version repository`_
 156   documentation.
 157
 158   .. _editable installs: docs/dev/repository.html#editable-installs
 159
 160 Optional steps:
 161
 162 * `Running the test suite`_
 163
 164 * `Converting the documentation`_
 165
 166
 167 GNU/Linux, BSDs, Unix, Mac OS X, etc.
 168 -------------------------------------
 169
 170 1. Open a shell.
 171
 172 2. Go to the directory containing ``setup.py``::
 173
 174        cd <archive_directory_path>
 175
 176 3. Install the package (you may need root permissions to complete this
 177    step)::
 178
 179        su
 180        (enter admin password)
 181        python3 setup.py install
 182
 183    If the python executable isn't on your path, you'll have to specify
 184    the complete path, such as ``/usr/local/bin/python``.
 185
 186    To install for a specific Python version, use this version in the
 187    setup call, e.g. ::
 188
 189        python3.7 setup.py install
 190
 191    To install for different Python versions, repeat step 3 for every
 192    required version. The last installed version will be used in the
 193    `shebang line`_ of the `front-end scripts`_.
 194
 195    .. _shebang line: https://en.wikipedia.org/wiki/Shebang_%28Unix%29
 196
 197 Windows
 198 -------
 199
 200 Just double-click ``install.py``.  If this doesn't work, try the
 201 following:
 202
 203 1. Open a DOS Box (Command Shell, MS-DOS Prompt, or whatever they're
 204    calling it these days).
 205
 206 2. Go to the directory created by expanding the archive::
 207
 208        cd <archive_directory_path>
 209
 210 3. Install the package::
 211
 212        <path_to_python.exe>\python setup.py install
 213
 214    To install for a specific python version, specify the Python
 215    executable for this version.
 216
 217    To install for different Python versions, repeat step 3 for every
 218    required version.
 219
 220
 221 Usage
 222 =====
 223
 224 There are many front-end tools in the unpacked "tools" subdirectory.
 225 Installation under Unix places copies in the PATH.
 226 You may want to begin with the "rst2html.py" front-end tool.  Most
 227 tools take up to two arguments, the source path and destination path,
 228 with STDIN and STDOUT being the defaults.  Use the ``--help`` option to
 229 the front-end tools for details on options and arguments.  See
 230 `Docutils Front-End Tools`_ for full documentation.
 231
 232 The package modules are continually growing and evolving.  The
 233 ``docutils.statemachine`` module is usable independently.  It contains
 234 extensive inline documentation (in reStructuredText format of course).
 235
 236 Contributions are welcome!
 237
 238 .. _front-end scripts:
 239 .. _Docutils Front-End Tools: docs/user/tools.html
 240
 241 Project Files & Directories
 242 ===========================
 243
 244 * README.txt: You're reading it.
 245
 246 * COPYING.txt: Public Domain Dedication and copyright details for
 247   non-public-domain files (most are PD).
 248
 249 * FAQ.txt: Frequently Asked Questions (with answers!).
 250
 251 * RELEASE-NOTES.txt: Summary of the major changes in recent releases.
 252
 253 * HISTORY.txt: A detailed change log, for the current and all previous
 254   project releases.
 255
 256 * BUGS.txt: Known bugs, and how to report a bug.
 257
 258 * THANKS.txt: List of contributors.
 259
 260 * setup.py: Installation script.  See "Installation" below.
 261
 262 * install.py: Quick & dirty installation script.  Just run it.  For
 263   any kind of customization or help though, setup.py must be used.
 264
 265 * docutils: The project source directory, installed as a Python
 266   package.
 267
 268 * docs: The project documentation directory.  Read ``docs/index.txt``
 269   for an overview.
 270
 271 * docs/user: The project user documentation directory.  Contains the
 272   following documents, among others:
 273
 274   - docs/user/tools.txt: Docutils Front-End Tools
 275   - docs/user/latex.txt: Docutils LaTeX Writer
 276   - docs/user/rst/quickstart.txt: A ReStructuredText Primer
 277   - docs/user/rst/quickref.html: Quick reStructuredText (HTML only)
 278
 279 * docs/ref: The project reference directory.
 280   ``docs/ref/rst/restructuredtext.txt`` is the reStructuredText
 281   reference.
 282
 283 * licenses: Directory containing copies of license files for
 284   non-public-domain files.
 285
 286 * tools: Directory for Docutils front-end tools.  See
 287   ``docs/user/tools.txt`` for documentation.
 288
 289 * test: Unit tests.  Not required to use the software, but very useful
 290   if you're planning to modify it.  See `Running the Test Suite`_
 291   below.
 292
 293
 294 Converting the documentation
 295 ============================
 296
 297 After unpacking and installing the Docutils package, the following
 298 shell commands will generate HTML for all included documentation::
 299
 300     cd <archive_directory_path>/tools
 301     ./buildhtml.py ../
 302
 303 On Windows systems, type::
 304
 305     cd <archive_directory_path>\tools
 306     python buildhtml.py ..
 307
 308 The final directory name of the ``<archive_directory_path>`` is
 309 "docutils" for snapshots.  For official releases, the directory may be
 310 called "docutils-X.Y.Z", where "X.Y.Z" is the release version.
 311 Alternatively::
 312
 313     cd <archive_directory_path>
 314     tools/buildhtml.py --config=tools/docutils.conf          (Unix)
 315     python tools\buildhtml.py --config=tools\docutils.conf   (Windows)
 316
 317 Some files may generate system messages (warnings and errors).  The
 318 ``docs/user/rst/demo.txt`` file (under the archive directory) contains
 319 five intentional errors.  (They test the error reporting mechanism!)
 320
 321
 322 Running the Test Suite
 323 ======================
 324
 325 The test suite is documented in `Docutils Testing`_ (docs/dev/testing.txt).
 326
 327 To run the entire test suite, open a shell and use the following
 328 commands::
 329
 330     cd <archive_directory_path>/test
 331     ./alltests.py
 332
 333 Under Windows, type::
 334
 335     cd <archive_directory_path>\test
 336     python alltests.py
 337
 338
 339 You should see a long line of periods, one for each test, and then a
 340 summary like this::
 341
 342     Ran 1111 tests in 24.653s
 343
 344     OK
 345     Elapsed time: 26.189 seconds
 346
 347 The number of tests will grow over time, and the times reported will
 348 depend on the computer running the tests.  The difference between the
 349 two times represents the time required to set up the tests (import
 350 modules, create data structures, etc.).
 351
 352 A copy of the test output is written to the file ``alltests.out``.
 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, look at the test output or use one of the `front-end scripts`_
 359 with the ``--version`` option.
 360
 361 .. _Docutils Testing: https://docutils.sourceforge.io/docs/dev/testing.html
 362 .. _open a bug report:
 363    https://sourceforge.net/p/docutils/bugs/
 364 .. _send an email: mailto:docutils-users@lists.sourceforge.net
 365    ?subject=Test%20suite%20failure
 366 .. _web interface: https://sourceforge.net/p/docutils/mailman/
 367
 368
 369 Getting Help
 370 ============
 371
 372 All documentation can be reached from the `Project Documentation
 373 Overview`_.
 374
 375 The SourceForge `project page`_ has links to the tracker, mailing
 376 lists, and code repository.
 377
 378 If you have further questions or need assistance with Docutils or
 379 reStructuredText, please post a message to the Docutils-users_ mailing
 380 list.
 381
 382 .. _Project Documentation Overview: docs/index.html
 383 .. _project page: https://sourceforge.net/p/docutils
 384 .. _Docutils-users: docs/user/mailing-lists.html#docutils-users
 385
 386 \f
 387 ..
 388    Local Variables:
 389    mode: indented-text
 390    indent-tabs-mode: nil
 391    sentence-end-double-space: t
 392    fill-column: 70
 393    End: