docutils/README.txt

   1 .. include:: docs/header0.txt
   2
   3 ==============================
   4  README: Docutils 0.21.2b.dev
   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.21, Docutils requires Python 3.9 or later.
  78 * Docutils versions 0.19 to 0.20.1 require Python 3.7 or later.
  79 * Docutils versions 0.16 to 0.18 require Python 2.7 or 3.5+.
  80
  81 .. _Python: https://www.python.org/.
  82
  83
  84 Recommendations
  85 ---------------
  86
  87 Docutils uses the following packages for enhanced functionality, if they
  88 are installed:
  89
  90 * The recommended installer is pip_, setuptools_ works, too.
  91
  92 * The `Python Imaging Library`_ (PIL) is used for some image
  93   manipulation operations.
  94
  95 * The `Pygments`_ package provides syntax highlight of "code" directives
  96   and roles.
  97
  98 * The `myst`_, `pycmark`_, or `recommonmark`_ parsers can be used to
  99   parse input in "Markdown" (CommonMark_) format.
 100
 101 The `Docutils Link List <docs/user/links.html>`__ records projects that
 102 users of Docutils and reStructuredText may find useful.
 103
 104 .. _pip: https://pypi.org/project/pip/
 105 .. _setuptools: https://pypi.org/project/setuptools/
 106 .. _Python Imaging Library: http://www.pythonware.com/products/pil/
 107 .. _Pygments: https://pypi.org/project/Pygments/
 108 .. _myst: https://pypi.org/project/myst-docutils/
 109 .. _pycmark: https://pypi.org/project/pycmark/
 110 .. _recommonmark: https://github.com/rtfd/recommonmark
 111 .. _CommonMark: https://spec.commonmark.org/0.30/
 112
 113
 114 Installation
 115 ============
 116
 117 The `Python Packaging User Guide`_ gives details how to
 118 `use pip for installing`_.
 119
 120 * The simplest way is to install the latest *stable release* from PyPi::
 121
 122       pip install docutils
 123
 124 * To install a *pre-relase*, append the option ``--pre``.
 125
 126 * To install a `development version`_ *from source*:
 127
 128   1. Open a shell
 129
 130   2. Go to the directory containing the file ``setup.py``.
 131
 132   3. Install the package with **one** of the following commands::
 133
 134          pip install -e .  # editable install
 135          pip install .     # regular install
 136
 137      or do a `"manual" install`_.
 138
 139   4. Optional steps:
 140
 141      * `Running the test suite`_
 142      * `Converting the documentation`_
 143
 144   See also the OS-specific installation instructions below and
 145   the `Docutils version repository`_ documentation.
 146
 147 * To install for a *specific Python version*, use this version in the
 148   setup call, e.g. ::
 149
 150        python3.11 -m pip install docutils
 151
 152   If the python executable isn't on your path, you'll have to specify the
 153   complete path, such as ``/usr/local/bin/python3.11``.
 154
 155   To install for different Python versions, repeat step 3 for every
 156   required version. The last installed version will be used for the
 157   ``docutils`` command line application.
 158
 159 .. _Python Packaging User Guide: https://packaging.python.org/en/latest/
 160 .. _use pip for installing:
 161     https://packaging.python.org/en/latest/tutorials/installing-packages/
 162     #use-pip-for-installing
 163 .. _"editable" install:
 164     https://pip.pypa.io/en/stable/topics/local-project-installs/
 165     #editable-installs
 166 .. _"manual" install: docs/dev/repository.html#manual-install
 167
 168
 169 GNU/Linux, BSDs, Unix, Mac OS X, etc.
 170 -------------------------------------
 171
 172 * Use ``su`` or ``sudo`` for a system-wide
 173   installation as ``root``, e.g.::
 174
 175       sudo pip install docutils
 176
 177
 178 Windows
 179 -------
 180
 181 * The Python FAQ explains `how to run a Python program under Windows`__.
 182
 183   __ https://docs.python.org/3/faq/windows.html
 184      #how-do-i-run-a-python-program-under-windows
 185
 186 * Usually, pip_ is automatically installed if you are using Python
 187   downloaded from https://python.org. If not, see the
 188   `pip documentation <https://pip.pypa.io/en/stable/installation/>`__.
 189
 190 * The command window should recognise the word ``py`` as an instruction to
 191   start the interpreter, e.g.
 192
 193        py -m pip install docutils
 194
 195   If this does not work, you may have to specify the full path to the
 196   Python executable.
 197
 198
 199 Usage
 200 =====
 201
 202 Start the "docutils" command line application with::
 203
 204     docutils [options] [<source> [<destination>]]
 205
 206 The default action is to convert a reStructuredText_ document to HTML5,
 207 for example::
 208
 209     docutils test.rst test.html
 210
 211 Read the ``--help`` option output for details on options and arguments and
 212 `Docutils Front-End Tools`_ for the full documentation of the various tools.
 213
 214 For programmatic use of the `docutils` Python package, read the
 215 `API Reference Material`_ and the source code.
 216 Remaining questions may be answered in the `Docutils Project
 217 Documentation`_ or the Docutils-users_ mailing list.
 218
 219 Contributions are welcome!
 220
 221 .. _reStructuredText: https://docutils.sourceforge.io/rst.html
 222 .. _front-end scripts:
 223 .. _Docutils Front-End Tools: docs/user/tools.html
 224 .. _API Reference Material: /docs/index.html
 225                             #api-reference-material-for-client-developers
 226 .. _Docutils Project Documentation: /docs/index.html
 227
 228
 229 Project Files & Directories
 230 ===========================
 231
 232 * README.txt: You're reading it.
 233
 234 * COPYING.txt: Public Domain Dedication and copyright details for
 235   non-public-domain files (most are PD).
 236
 237 * FAQ.txt: Frequently Asked Questions (with answers!).
 238
 239 * RELEASE-NOTES.txt: Summary of the major changes in recent releases.
 240
 241 * HISTORY.txt: A detailed change log, for the current and all previous
 242   project releases.
 243
 244 * BUGS.txt: Known bugs, and how to report a bug.
 245
 246 * THANKS.txt: List of contributors.
 247
 248 * setup.py: Installation script.  See "Installation" below.
 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
 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: