docutils/README.txt

   1 ==============================
   2  README: Docutils 0.18.2b.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    http://www.python.org/.
  21
  22    See Requirements_ below for details.
  23
  24 2. Install the latest stable release from PyPi with pip_::
  25
  26        python -m pip install docutils
  27
  28    To install a pre-relase, append the option ``--pre``.
  29    To install a `development version`_, follow the instructions in
  30    section `Installation`_ below.
  31
  32 3. Use the `front-end scripts`_ to convert reStructuredText documents.
  33    Try for example::
  34
  35        rst2html.py FAQ.txt FAQ.html         (Unix)
  36        python tools/rst2html.py FAQ.txt FAQ.html  (Windows)
  37
  38    See Usage_ below for details.
  39
  40 .. _pip: https://pypi.org/project/pip/
  41
  42
  43 Purpose
  44 =======
  45
  46 The purpose of the Docutils project is to create a set of tools for
  47 processing plaintext documentation into useful formats, such as HTML,
  48 LaTeX, troff (man pages), OpenOffice, and native XML.  Support for the
  49 following sources has been implemented:
  50
  51 * Standalone files.
  52
  53 * `PEPs (Python Enhancement Proposals)`_.
  54
  55 Support for the following sources is planned:
  56
  57 * Inline documentation from Python modules and packages, extracted
  58   with namespace context.
  59
  60 * Email (RFC-822 headers, quoted excerpts, signatures, MIME parts).
  61
  62 * Wikis, with global reference lookups of "wiki links".
  63
  64 * Compound documents, such as multiple chapter files merged into a
  65   book.
  66
  67 * And others as discovered.
  68
  69 .. _PEPs (Python Enhancement Proposals):
  70    http://www.python.org/peps/pep-0012.html
  71
  72
  73 Requirements
  74 ============
  75
  76 To run the code, Python_ must be installed.
  77
  78 * Docutils 0.16 and later supports Python 2.7 and 3.5+ natively.  [#2to3]_
  79 * Docutils 0.14 dropped Python 2.4, 2.5, 3.1 and 3.2 support.
  80 * Docutils 0.10 dropped Python 2.3 support.
  81 * From version 0.6, Docutils is compatible with Python 3. [#2to3]_
  82 * For Docutils 0.5, Python 2.2.1+ is required.
  83 * Up to Docutils 0.4, Python 2.1 is required.
  84
  85 .. [#2to3] Up to version 0.15, the Docutils codebase was translated
  86    "on-demand" using the 2to3 tool.
  87
  88 Recommendations
  89 ---------------
  90
  91 Docutils uses the following packages for enhanced functionality, if they
  92 are installed:
  93
  94 * Installation_ is usually done with pip_ or setuptools_.
  95
  96 * The `Python Imaging Library`_, or PIL, is used for some image
  97   manipulation operations.
  98
  99 * The `Pygments`_ package provides syntax highlight of "code" directives
 100   and roles.
 101
 102 * The `recommonmark`_ parser is used to parse input in Markdown format.
 103
 104 The `Docutils Link List <docs/user/links.html>`__ records projects that
 105 users of Docutils and reStructuredText may find useful.
 106
 107 .. _Python: http://www.python.org/.
 108 .. _Python Imaging Library: http://www.pythonware.com/products/pil/
 109 .. _Pygments: https://pypi.org/project/Pygments/
 110 .. _setuptools: https://pypi.org/project/setuptools/
 111 .. _recommonmark: https://github.com/rtfd/recommonmark
 112
 113
 114 Development version
 115 ===================
 116
 117 While we are trying to follow a "release early & often" policy,
 118 features are added frequently.  Since the code in the repository_
 119 is usually in a bug-free state, we recommend using a current snapshot
 120 or a working copy.
 121
 122 To get a _`snapshot`, go to the code page and click the download snapshot
 123 button:
 124
 125 * Docutils code, documentation, front-end tools, and tests:
 126   https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/
 127
 128 * Sandbox (experimental, contributed code):
 129   https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/sandbox/
 130
 131 To keep up to date on the latest developments, download fresh copies of the
 132 snapshots regularly or use a `working copy of the Docutils code repository`__.
 133
 134 Continue with the `Installation`_ instructions below.
 135
 136 .. _repository: docs/dev/repository.html
 137 __ docs/dev/repository.html#checking-out-the-repository
 138
 139 Installation
 140 ============
 141
 142 Steps to install Docutils from source:
 143
 144 * Go to the directory containing the file ``setup.py``.
 145
 146   A snapshot_ must be unpacked in a temporary directory (**not** directly in
 147   Python's ``site-packages``) first.
 148
 149 * Run ``setup.py install``. [#setup-requires-setuptools]_
 150   On Windows systems it may be sufficient to double-click ``install.py``.
 151
 152 .. [#setup-requires-setuptools] ``setup.py`` requires the `setuptools`_
 153    package. For a manual install see the options in `Setting up for Docutils
 154    development`__.
 155
 156    __ docs/dev/policies.html#setting-up-for-docutils-development
 157
 158 Optional steps:
 159
 160 * `running the test suite`_
 161
 162 * `converting the documentation`_
 163
 164 OS-specific installation instructions follow.
 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        python 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 ``rst2*.py`` wrapper scripts.
 194
 195    .. _shebang line: http://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 If any of the tests fail, please `open a bug report`_ or `send an email`_
 353 (see `Bugs <BUGS.html>`_).
 354 Please include all relevant output, information about your operating
 355 system, Python version, and Docutils version.  To see the Docutils
 356 version, use one of the ``rst2*`` front ends or ``tools/quicktest.py``
 357 with the ``--version`` option, e.g.::
 358
 359     cd ../tools
 360     ./quicktest.py --version
 361
 362 Windows users type these commands::
 363
 364     cd ..\tools
 365     python quicktest.py --version
 366
 367
 368 .. _Docutils Testing: http://docutils.sourceforge.net/docs/dev/testing.html
 369 .. _open a bug report:
 370    http://sourceforge.net/p/docutils/bugs/
 371 .. _send an email: mailto:docutils-users@lists.sourceforge.net
 372    ?subject=Test%20suite%20failure
 373 .. _web interface: https://sourceforge.net/p/docutils/mailman/
 374
 375
 376 Getting Help
 377 ============
 378
 379 If you have questions or need assistance with Docutils or
 380 reStructuredText, please post a message to the Docutils-users_ mailing
 381 list.
 382
 383 .. _Docutils-users: docs/user/mailing-lists.html#docutils-users
 384
 385 \f
 386 ..
 387    Local Variables:
 388    mode: indented-text
 389    indent-tabs-mode: nil
 390    sentence-end-double-space: t
 391    fill-column: 70
 392    End: