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