docutils/README.txt

   1 .. include:: docs/header0.txt
   2
   3 =========================
   4  README: Docutils 0.20.1
   5 =========================
   6
   7 :Author: David Goodger
   8 :Contact: goodger@python.org
   9 :Date: $Date$
  10 :Web site: https://docutils.sourceforge.io/
  11 :Copyright: This document has been placed in the public domain.
  12
  13 .. contents::
  14
  15
  16 Quick-Start
  17 ===========
  18
  19 This is for those who want to get up & running quickly.
  20
  21 1. Docutils requires **Python**, available from
  22    https://www.python.org/.
  23    See Dependencies_ below for details.
  24
  25 2. Install the latest stable release from PyPi with pip_::
  26
  27        pip install docutils
  28
  29    For alternatives and details, see section `Installation`_ below.
  30
  31 3. Use the `front-end scripts`_ to convert reStructuredText documents.
  32    Try for example::
  33
  34        docutils FAQ.txt FAQ.html
  35
  36    See Usage_ below for details.
  37
  38
  39 Purpose
  40 =======
  41
  42 The purpose of the Docutils project is to provide a set of tools for
  43 processing plaintext documentation into useful formats, such as HTML,
  44 LaTeX, troff (man pages), OpenOffice, and native XML.  Support for the
  45 following sources has been implemented:
  46
  47 * Standalone files.
  48
  49 * `PEPs (Python Enhancement Proposals)`_.
  50
  51 Support for the following sources is planned or provided by
  52 `third party tools`_:
  53
  54 * Inline documentation from Python modules and packages, extracted
  55   with namespace context.
  56
  57 * Email (RFC-822 headers, quoted excerpts, signatures, MIME parts).
  58
  59 * Wikis, with global reference lookups of "wiki links".
  60
  61 * Compound documents, such as multiple chapter files merged into a
  62   book.
  63
  64 * And others as discovered.
  65
  66 .. _PEPs (Python Enhancement Proposals):
  67    https://peps.python.org/pep-0012
  68 .. _third party tools: docs/user/links.html#related-applications
  69
  70
  71 Dependencies
  72 ============
  73
  74 To run the code, Python_ must be installed.
  75 (Python is pre-installed with most Linux distributions.)
  76
  77 * Since version 0.19, Docutils requires Python 3.7 or later.
  78 * Docutils 0.16 to 0.18 require Python 2.7 or 3.5+.
  79
  80 .. _Python: https://www.python.org/.
  81
  82
  83 Recommendations
  84 ---------------
  85
  86 Docutils uses the following packages for enhanced functionality, if they
  87 are installed:
  88
  89 * The recommended installer is pip_, setuptools_ works, too.
  90
  91 * The `Python Imaging Library`_ (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`_, `pycmark`_, or `recommonmark`_ parsers can be used to
  98   parse input in "Markdown" (CommonMark_) 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 .. _pycmark: https://pypi.org/project/pycmark/
 109 .. _recommonmark: https://github.com/rtfd/recommonmark
 110 .. _CommonMark: https://spec.commonmark.org/0.30/
 111
 112
 113 Installation
 114 ============
 115
 116 The `Python Packaging User Guide`_ gives details how to
 117 `use pip for installing`_.
 118
 119 * The simplest way is to install the latest *stable release* from PyPi::
 120
 121       pip install docutils
 122
 123 * To install a *pre-relase*, append the option ``--pre``.
 124
 125 * To install a `development version`_ *from source*:
 126
 127   1. Open a shell
 128
 129   2. Go to the directory containing the file ``setup.py``.
 130
 131   3. Install the package with **one** of the following commands::
 132
 133          pip install -e .  # editable install
 134          pip install .     # regular install
 135          python setup.py   # regular install with setuptools
 136
 137   4. Optional steps:
 138
 139      * `Running the test suite`_
 140      * `Converting the documentation`_
 141
 142   See also the OS-specific installation instructions below and
 143   the `Docutils version repository`_ documentation.
 144
 145 * To install for a *specific Python version*, use this version in the
 146   setup call, e.g. ::
 147
 148        python3.11 -m pip install docutils
 149
 150   If the python executable isn't on your path, you'll have to specify the
 151   complete path, such as ``/usr/local/bin/python3.11``.
 152
 153   To install for different Python versions, repeat step 3 for every
 154   required version. The last installed version will be used for the
 155   ``docutils`` command line application.
 156
 157 .. _Python Packaging User Guide: https://packaging.python.org/en/latest/
 158 .. _use pip for installing:
 159     https://packaging.python.org/en/latest/tutorials/installing-packages/
 160     #use-pip-for-installing
 161 .. _"editable" install:
 162     https://pip.pypa.io/en/stable/topics/local-project-installs/
 163     #editable-installs
 164
 165
 166 GNU/Linux, BSDs, Unix, Mac OS X, etc.
 167 -------------------------------------
 168
 169 * Use ``su`` or ``sudo`` for a system-wide
 170   installation as ``root``, e.g.::
 171
 172       sudo pip install docutils
 173
 174
 175 Windows
 176 -------
 177
 178 * The Python FAQ explains `how to run a Python program under Windows`__.
 179
 180   __ https://docs.python.org/3/faq/windows.html
 181      #how-do-i-run-a-python-program-under-windows
 182
 183 * Usually, pip_ is automatically installed if you are using Python
 184   downloaded from https://python.org. If not, see the
 185   `pip documentation <https://pip.pypa.io/en/stable/installation/>`__.
 186
 187 * The command window should recognise the word ``py`` as an instruction to
 188   start the interpreter, e.g.
 189
 190        py -m pip install docutils
 191
 192   If this does not work, you may have to specify the full path to the
 193   Python executable.
 194
 195
 196 Usage
 197 =====
 198
 199 Start the "docutils" command line application with::
 200
 201     docutils [options] [<source> [<destination>]]
 202
 203 The default action is to convert a reStructuredText_ document to HTML5,
 204 for example::
 205
 206     docutils test.rst test.html
 207
 208 Read the ``--help`` option output for details on options and arguments and
 209 `Docutils Front-End Tools`_ for the full documentation of the various tools.
 210
 211 For programmatic use of the `docutils` Python package, read the
 212 `API Reference Material`_ and the source code.
 213 Remaining questions may be answered in the `Docutils Project
 214 Documentation`_ or the Docutils-users_ mailing list.
 215
 216 Contributions are welcome!
 217
 218 .. _reStructuredText: https://docutils.sourceforge.io/rst.html
 219 .. _front-end scripts:
 220 .. _Docutils Front-End Tools: docs/user/tools.html
 221 .. _API Reference Material: /docs/index.html
 222                             #api-reference-material-for-client-developers
 223 .. _Docutils Project Documentation: /docs/index.html
 224
 225
 226 Project Files & Directories
 227 ===========================
 228
 229 * README.txt: You're reading it.
 230
 231 * COPYING.txt: Public Domain Dedication and copyright details for
 232   non-public-domain files (most are PD).
 233
 234 * FAQ.txt: Frequently Asked Questions (with answers!).
 235
 236 * RELEASE-NOTES.txt: Summary of the major changes in recent releases.
 237
 238 * HISTORY.txt: A detailed change log, for the current and all previous
 239   project releases.
 240
 241 * BUGS.txt: Known bugs, and how to report a bug.
 242
 243 * THANKS.txt: List of contributors.
 244
 245 * setup.py: Installation script.  See "Installation" below.
 246
 247 * install.py: Quick & dirty installation script.  Just run it.  For
 248   any kind of customization or help though, setup.py must be used.
 249
 250 * docutils: The project source directory, installed as a Python
 251   package.
 252
 253 * docs: The project documentation directory.  Read ``docs/index.txt``
 254   for an overview.
 255
 256 * docs/user: The project user documentation directory.  Contains the
 257   following documents, among others:
 258
 259   - docs/user/tools.txt: Docutils Front-End Tools
 260   - docs/user/latex.txt: Docutils LaTeX Writer
 261   - docs/user/rst/quickstart.txt: A ReStructuredText Primer
 262   - docs/user/rst/quickref.html: Quick reStructuredText (HTML only)
 263
 264 * docs/ref: The project reference directory.
 265   ``docs/ref/rst/restructuredtext.txt`` is the reStructuredText
 266   reference.
 267
 268 * licenses: Directory containing copies of license files for
 269   non-public-domain files.
 270
 271 * tools: Directory for Docutils front-end tools.  See
 272   ``docs/user/tools.txt`` for documentation.
 273
 274 * test: Unit tests.  Not required to use the software, but very useful
 275   if you're planning to modify it.  See `Running the Test Suite`_
 276   below.
 277
 278
 279 Development version
 280 ===================
 281
 282 While we are trying to follow a "release early & often" policy,
 283 features are added frequently.
 284 We recommend using a current snapshot or a working copy of the repository.
 285
 286 Repository check-out:
 287   To keep up to date on the latest developments,
 288   use a `working copy`__ of the `Docutils version repository`_.
 289
 290 Snapshots:
 291   To get a repository _`snapshot`, go to
 292   https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/
 293   and click the download snapshot button.
 294
 295   Unpack in a temporary directory,
 296   **not** directly in Python's ``site-packages``.
 297
 298 Continue with the `Installation`_ instructions below.
 299
 300 __ docs/dev/repository.html#checking-out-the-repository
 301 .. _Docutils version repository: docs/dev/repository.html
 302 .. _sandbox: https://docutils.sourceforge.io/sandbox/README.html
 303
 304
 305 Converting the documentation
 306 ============================
 307
 308 After unpacking and installing the Docutils package, the following
 309 shell commands will generate HTML for all included documentation::
 310
 311     cd <archive_directory_path>
 312     tools/buildhtml.py .
 313
 314 On Windows systems, type::
 315
 316     cd <archive_directory_path>
 317     py tools\buildhtml.py ..
 318
 319 The final directory name of the ``<archive_directory_path>`` is
 320 "docutils" for snapshots.  For official releases, the directory may be
 321 called "docutils-X.Y.Z", where "X.Y.Z" is the release version.
 322
 323 Some files may generate system messages (warnings and errors).  The
 324 ``docs/user/rst/demo.txt`` file (under the archive directory) contains
 325 five intentional errors.  (They test the error reporting mechanism!)
 326
 327
 328 Running the Test Suite
 329 ======================
 330
 331 The test suite is documented in `Docutils Testing`_ (docs/dev/testing.txt).
 332
 333 To run the entire test suite, open a shell and use the following
 334 commands::
 335
 336     cd <archive_directory_path>/test
 337     ./alltests.py
 338
 339 Under Windows, type::
 340
 341     cd <archive_directory_path>\test
 342     python alltests.py
 343
 344
 345 You should see a long line of periods, one for each test, and then a
 346 summary like this::
 347
 348     Ran 1744 tests in 5.859s
 349
 350     OK (skipped=1)
 351     Elapsed time: 6.235 seconds
 352
 353 The number of tests will grow over time, and the times reported will
 354 depend on the computer running the tests.
 355 Some test are skipped, if optional dependencies (`recommendations`_)
 356 are missing.
 357 The difference between the two times represents the time required to set
 358 up the tests (import modules, create data structures, etc.).
 359
 360 A copy of the test output is written to the file ``alltests.out``.
 361
 362 If any of the tests fail, please `open a bug report`_ or `send an email`_
 363 (see `Bugs <BUGS.html>`_).
 364 Please include all relevant output, information about your operating
 365 system, Python version, and Docutils version.  To see the Docutils
 366 version, look at the test output or use ::
 367
 368     docutils --version
 369
 370 .. _Docutils Testing: https://docutils.sourceforge.io/docs/dev/testing.html
 371 .. _open a bug report:
 372    https://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 All documentation can be reached from the `Project Documentation
 382 Overview`_.
 383
 384 The SourceForge `project page`_ has links to the tracker, mailing
 385 lists, and code repository.
 386
 387 If you have further questions or need assistance with Docutils or
 388 reStructuredText, please post a message to the Docutils-users_ mailing
 389 list.
 390
 391 .. _Project Documentation Overview: docs/index.html
 392 .. _project page: https://sourceforge.net/p/docutils
 393 .. _Docutils-users: docs/user/mailing-lists.html#docutils-users
 394
 395 \f
 396 ..
 397    Local Variables:
 398    mode: indented-text
 399    indent-tabs-mode: nil
 400    sentence-end-double-space: t
 401    fill-column: 70
 402    End: