docutils/README.txt

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