1 .. include:: docs/header0.txt
3 ===============================
4 README: Docutils 0.21b.dev
5 ===============================
8 :Contact: goodger@python.org
10 :Web site: https://docutils.sourceforge.io/
11 :Copyright: This document has been placed in the public domain.
19 This is for those who want to get up & running quickly.
21 1. Docutils requires **Python**, available from
22 https://www.python.org/.
23 See Dependencies_ below for details.
25 2. Install the latest stable release from PyPi with pip_::
29 For alternatives and details, see section `Installation`_ below.
31 3. Use the `front-end scripts`_ to convert reStructuredText documents.
34 docutils FAQ.txt FAQ.html
36 See Usage_ below for details.
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:
49 * `PEPs (Python Enhancement Proposals)`_.
51 Support for the following sources is planned or provided by
54 * Inline documentation from Python modules and packages, extracted
55 with namespace context.
57 * Email (RFC-822 headers, quoted excerpts, signatures, MIME parts).
59 * Wikis, with global reference lookups of "wiki links".
61 * Compound documents, such as multiple chapter files merged into a
64 * And others as discovered.
66 .. _PEPs (Python Enhancement Proposals):
67 https://peps.python.org/pep-0012
68 .. _third party tools: docs/user/links.html#related-applications
74 To run the code, Python_ must be installed.
75 (Python is pre-installed with most Linux distributions.)
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+.
81 .. _Python: https://www.python.org/.
87 Docutils uses the following packages for enhanced functionality, if they
90 * The recommended installer is pip_, setuptools_ works, too.
92 * The `Python Imaging Library`_ (PIL) is used for some image
93 manipulation operations.
95 * The `Pygments`_ package provides syntax highlight of "code" directives
98 * The `myst`_, `pycmark`_, or `recommonmark`_ parsers can be used to
99 parse input in "Markdown" (CommonMark_) format.
101 The `Docutils Link List <docs/user/links.html>`__ records projects that
102 users of Docutils and reStructuredText may find useful.
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/
117 The `Python Packaging User Guide`_ gives details how to
118 `use pip for installing`_.
120 * The simplest way is to install the latest *stable release* from PyPi::
124 * To install a *pre-relase*, append the option ``--pre``.
126 * To install a `development version`_ *from source*:
130 2. Go to the directory containing the file ``setup.py``.
132 3. Install the package with **one** of the following commands::
134 pip install -e . # editable install
135 pip install . # regular install
137 or do a `"manual" install`_.
141 * `Running the test suite`_
142 * `Converting the documentation`_
144 See also the OS-specific installation instructions below and
145 the `Docutils version repository`_ documentation.
147 * To install for a *specific Python version*, use this version in the
150 python3.11 -m pip install docutils
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``.
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.
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/
166 .. _"manual" install: docs/dev/repository.html#manual-install
169 GNU/Linux, BSDs, Unix, Mac OS X, etc.
170 -------------------------------------
172 * Use ``su`` or ``sudo`` for a system-wide
173 installation as ``root``, e.g.::
175 sudo pip install docutils
181 * The Python FAQ explains `how to run a Python program under Windows`__.
183 __ https://docs.python.org/3/faq/windows.html
184 #how-do-i-run-a-python-program-under-windows
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/>`__.
190 * The command window should recognise the word ``py`` as an instruction to
191 start the interpreter, e.g.
193 py -m pip install docutils
195 If this does not work, you may have to specify the full path to the
202 Start the "docutils" command line application with::
204 docutils [options] [<source> [<destination>]]
206 The default action is to convert a reStructuredText_ document to HTML5,
209 docutils test.rst test.html
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.
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.
219 Contributions are welcome!
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
229 Project Files & Directories
230 ===========================
232 * README.txt: You're reading it.
234 * COPYING.txt: Public Domain Dedication and copyright details for
235 non-public-domain files (most are PD).
237 * FAQ.txt: Frequently Asked Questions (with answers!).
239 * RELEASE-NOTES.txt: Summary of the major changes in recent releases.
241 * HISTORY.txt: A detailed change log, for the current and all previous
244 * BUGS.txt: Known bugs, and how to report a bug.
246 * THANKS.txt: List of contributors.
248 * setup.py: Installation script. See "Installation" below.
250 * docutils: The project source directory, installed as a Python
253 * docs: The project documentation directory. Read ``docs/index.txt``
256 * docs/user: The project user documentation directory. Contains the
257 following documents, among others:
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)
264 * docs/ref: The project reference directory.
265 ``docs/ref/rst/restructuredtext.txt`` is the reStructuredText
268 * licenses: Directory containing copies of license files for
269 non-public-domain files.
271 * tools: Directory for Docutils front-end tools. See
272 ``docs/user/tools.txt`` for documentation.
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`_
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.
286 Repository check-out:
287 To keep up to date on the latest developments,
288 use a `working copy`__ of the `Docutils version repository`_.
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.
295 Unpack in a temporary directory,
296 **not** directly in Python's ``site-packages``.
298 Continue with the `Installation`_ instructions below.
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
305 Converting the documentation
306 ============================
308 After unpacking and installing the Docutils package, the following
309 shell commands will generate HTML for all included documentation::
311 cd <archive_directory_path>
314 On Windows systems, type::
316 cd <archive_directory_path>
317 py tools\buildhtml.py ..
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.
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!)
328 Running the Test Suite
329 ======================
331 The test suite is documented in `Docutils Testing`_ (docs/dev/testing.txt).
333 To run the entire test suite, open a shell and use the following
336 cd <archive_directory_path>/test
339 Under Windows, type::
341 cd <archive_directory_path>\test
345 You should see a long line of periods, one for each test, and then a
348 Ran 1744 tests in 5.859s
351 Elapsed time: 6.235 seconds
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`_)
357 The difference between the two times represents the time required to set
358 up the tests (import modules, create data structures, etc.).
360 A copy of the test output is written to the file ``alltests.out``.
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 ::
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/
381 All documentation can be reached from the `Project Documentation
384 The SourceForge `project page`_ has links to the tracker, mailing
385 lists, and code repository.
387 If you have further questions or need assistance with Docutils or
388 reStructuredText, please post a message to the Docutils-users_ mailing
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
399 indent-tabs-mode: nil
400 sentence-end-double-space: t