CINXE.COM

<!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <meta charset="utf-8" /> <meta name="generator" content="Docutils 0.22b.dev: https://docutils.sourceforge.io/" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="author" content="David Goodger" /> <meta name="dcterms.date" content="2024-10-18" /> <meta name="dcterms.rights" content="This document has been placed in the public domain." /> <title>README: Docutils 0.22b.dev</title> <link rel="schema.dcterms" href="http://purl.org/dc/terms/"/> <link rel="stylesheet" href="docutils/writers/html5_polyglot/minimal.css" type="text/css" /> <link rel="stylesheet" href="docutils/writers/html5_polyglot/responsive.css" type="text/css" /> <link rel="stylesheet" href="docutils/writers/html5_polyglot/italic-field-names.css" type="text/css" /> </head> <body class="with-toc"> <header> <p><a class="reference external" href="https://docutils.sourceforge.io">Docutils</a> | <a class="reference external" href="docs/index.html">Overview</a> | <a class="reference external" href="docs/index.html#project-fundamentals">About</a> | <a class="reference external" href="docs/index.html#user">Users</a> | <a class="reference external" href="docs/index.html#ref">Reference</a> | <a class="reference external" href="docs/index.html#howto">Developers</a></p> </header> <main id="readme-docutils-0-22b-dev"> <h1 class="title">README: Docutils 0.22b.dev</h1> <dl class="docinfo"> <dt class="author">Author<span class="colon">:</span></dt> <dd class="author"><p>David Goodger</p></dd> <dt class="contact">Contact<span class="colon">:</span></dt> <dd class="contact"><a class="reference external" href="mailto:goodger@python.org">goodger@python.org</a></dd> <dt class="date">Date<span class="colon">:</span></dt> <dd class="date">2024-10-18</dd> <dt class="web-site">Web site<span class="colon">:</span></dt> <dd class="web-site"><p><a class="reference external" href="https://docutils.sourceforge.io/">https://docutils.sourceforge.io/</a></p> </dd> <dt class="copyright">Copyright<span class="colon">:</span></dt> <dd class="copyright">This document has been placed in the public domain.</dd> </dl>  <nav class="contents" id="contents" role="doc-toc"> <p class="topic-title"><a class="reference internal" href="#top">Contents</a></p> <ul class="simple"> <li><p><a class="reference internal" href="#quick-start" id="toc-entry-1">Quick-Start</a></p></li> <li><p><a class="reference internal" href="#purpose" id="toc-entry-2">Purpose</a></p></li> <li><p><a class="reference internal" href="#dependencies" id="toc-entry-3">Dependencies</a></p> <ul> <li><p><a class="reference internal" href="#recommendations" id="toc-entry-4">Recommendations</a></p></li> </ul> </li> <li><p><a class="reference internal" href="#installation" id="toc-entry-5">Installation</a></p> <ul> <li><p><a class="reference internal" href="#gnu-linux-bsds-unix-mac-os-x-etc" id="toc-entry-6">GNU/Linux, BSDs, Unix, Mac OS X, etc.</a></p></li> <li><p><a class="reference internal" href="#windows" id="toc-entry-7">Windows</a></p></li> </ul> </li> <li><p><a class="reference internal" href="#usage" id="toc-entry-8">Usage</a></p></li> <li><p><a class="reference internal" href="#project-files-directories" id="toc-entry-9">Project Files & Directories</a></p></li> <li><p><a class="reference internal" href="#development-version" id="toc-entry-10">Development version</a></p></li> <li><p><a class="reference internal" href="#converting-the-documentation" id="toc-entry-11">Converting the documentation</a></p></li> <li><p><a class="reference internal" href="#running-the-test-suite" id="toc-entry-12">Running the Test Suite</a></p></li> <li><p><a class="reference internal" href="#getting-help" id="toc-entry-13">Getting Help</a></p></li> </ul> </nav> <section id="quick-start"> <h2><a class="toc-backref" href="#toc-entry-1" role="doc-backlink">Quick-Start</a><a class="self-link" title="link to this section" href="#quick-start"></a></h2> <p>This is for those who want to get up & running quickly.</p> <ol class="arabic"> <li><p>Docutils requires <strong>Python</strong>, available from <a class="reference external" href="https://www.python.org/">https://www.python.org/</a>. See <a class="reference internal" href="#dependencies">Dependencies</a> below for details.</p></li> <li><p>Install the latest stable release from PyPi with <a class="reference external" href="https://pypi.org/project/pip/">pip</a>:</p> <pre class="literal-block">pip install docutils</pre> <p>For alternatives and details, see section <a class="reference internal" href="#installation">Installation</a> below.</p> </li> <li><p>Use the <a class="reference external" href="docs/user/tools.html">front-end scripts</a> to convert reStructuredText documents. Try for example:</p> <pre class="literal-block">docutils FAQ.rst FAQ.html</pre> <p>See <a class="reference internal" href="#usage">Usage</a> below for details.</p> </li> </ol> </section> <section id="purpose"> <h2><a class="toc-backref" href="#toc-entry-2" role="doc-backlink">Purpose</a><a class="self-link" title="link to this section" href="#purpose"></a></h2> <p>The purpose of the Docutils project is to provide a set of tools for processing plaintext documentation into useful formats, such as HTML, LaTeX, troff (man pages), OpenOffice, and native XML. Support for the following sources has been implemented:</p> <ul class="simple"> <li><p>Standalone files.</p></li> <li><p><a class="reference external" href="https://peps.python.org/pep-0012">PEPs (Python Enhancement Proposals)</a>.</p></li> </ul> <p>Support for the following sources is planned or provided by <a class="reference external" href="docs/user/links.html#related-applications">third party tools</a>:</p> <ul class="simple"> <li><p>Inline documentation from Python modules and packages, extracted with namespace context.</p></li> <li><p>Email (RFC-822 headers, quoted excerpts, signatures, MIME parts).</p></li> <li><p>Wikis, with global reference lookups of "wiki links".</p></li> <li><p>Compound documents, such as multiple chapter files merged into a book.</p></li> <li><p>And others as discovered.</p></li> </ul> </section> <section id="dependencies"> <h2><a class="toc-backref" href="#toc-entry-3" role="doc-backlink">Dependencies</a><a class="self-link" title="link to this section" href="#dependencies"></a></h2> <p>To run the code, <a class="reference external" href="https://www.python.org/.">Python</a> must be installed. (Python is pre-installed with most Linux distributions.)</p> <ul class="simple"> <li><p>Since version 0.21, Docutils requires Python聽3.9 or later.</p></li> <li><p>Docutils versions 0.19 to 0.20.1 require Python聽3.7 or later.</p></li> <li><p>Docutils versions 0.16 to 0.18 require Python聽2.7 or 3.5+.</p></li> </ul> <p>The <strong>type hints</strong> added in version 0.22 use Python聽3.10 syntax. However, the Python interpreter treats them as annotations unless <span class="docutils literal">typing.TYPE_CHECKING</span> is set to <span class="docutils literal">True</span>.</p> <section id="recommendations"> <h3><a class="toc-backref" href="#toc-entry-4" role="doc-backlink">Recommendations</a><a class="self-link" title="link to this section" href="#recommendations"></a></h3> <p>Docutils uses the following packages for enhanced functionality, if they are installed:</p> <ul class="simple"> <li><p>The recommended installer is <a class="reference external" href="https://pypi.org/project/pip/">pip</a>, <a class="reference external" href="https://pypi.org/project/setuptools/">setuptools</a> works, too.</p></li> <li><p>The <a class="reference external" href="http://www.pythonware.com/products/pil/">Python Imaging Library</a> (PIL) is used for some image manipulation operations.</p></li> <li><p>The <a class="reference external" href="https://pypi.org/project/Pygments/">Pygments</a> package provides syntax highlight of "code" directives and roles.</p></li> <li><p>The <a class="reference external" href="https://pypi.org/project/myst-docutils/">myst</a>, <a class="reference external" href="https://pypi.org/project/pycmark/">pycmark</a>, or <a class="reference external" href="https://github.com/rtfd/recommonmark">recommonmark</a> parsers can be used to parse input in "Markdown" (<a class="reference external" href="https://spec.commonmark.org/0.30/">CommonMark</a>) format.</p></li> </ul> <p>The <a class="reference external" href="docs/user/links.html">Docutils Link List</a> records projects that users of Docutils and reStructuredText may find useful.</p> </section> </section> <section id="installation"> <h2><a class="toc-backref" href="#toc-entry-5" role="doc-backlink">Installation</a><a class="self-link" title="link to this section" href="#installation"></a></h2> <p>The <a class="reference external" href="https://packaging.python.org/en/latest/">Python Packaging User Guide</a> gives details how to <a class="reference external" href="https://packaging.python.org/en/latest/tutorials/installing-packages/#use-pip-for-installing">use pip for installing</a>.</p> <ul> <li><p>The simplest way is to install the latest <em>stable release</em> from PyPi:</p> <pre class="literal-block">pip install docutils</pre> </li> <li><p>To install a <em>pre-relase</em>, append the option <span class="docutils literal"><span class="pre">--pre</span></span>.</p></li> <li><p>To install a <a class="reference internal" href="#development-version">development version</a> <em>from source</em>:</p> <ol class="arabic"> <li><p>Open a shell</p></li> <li><p>Go to the directory containing the <span class="docutils literal">pyproject.toml</span> file.</p></li> <li><p>Install the package with <strong>one</strong> of the following commands:</p> <pre class="literal-block">pip install -e . # editable install pip install . # regular install</pre> <p>or do a <a class="reference external" href="docs/dev/repository.html#manual-install">"manual" install</a>.</p> </li> <li><p>Optional steps:</p> <ul class="simple"> <li><p><a class="reference internal" href="#running-the-test-suite">Running the test suite</a></p></li> <li><p><a class="reference internal" href="#converting-the-documentation">Converting the documentation</a></p></li> </ul> </li> </ol> <p>See also the OS-specific installation instructions below and the <a class="reference external" href="docs/dev/repository.html">Docutils version repository</a> documentation.</p> </li> <li><p>To install for a <em>specific Python version</em>, use this version in the setup call, e.g.</p> <pre class="literal-block">python3.11 -m pip install docutils</pre> <p>If the python executable isn't on your path, you'll have to specify the complete path, such as <span class="docutils literal">/usr/local/bin/python3.11</span>.</p> <p>To install for different Python versions, repeat step聽3 for every required version. The last installed version will be used for the <span class="docutils literal">docutils</span> command line application.</p> </li> </ul> <section id="gnu-linux-bsds-unix-mac-os-x-etc"> <h3><a class="toc-backref" href="#toc-entry-6" role="doc-backlink">GNU/Linux, BSDs, Unix, Mac OS X, etc.</a><a class="self-link" title="link to this section" href="#gnu-linux-bsds-unix-mac-os-x-etc"></a></h3> <ul> <li><p>Use <span class="docutils literal">su</span> or <span class="docutils literal">sudo</span> for a system-wide installation as <span class="docutils literal">root</span>, e.g.:</p> <pre class="literal-block">sudo pip install docutils</pre> </li> </ul> </section> <section id="windows"> <h3><a class="toc-backref" href="#toc-entry-7" role="doc-backlink">Windows</a><a class="self-link" title="link to this section" href="#windows"></a></h3> <ul> <li><p>The Python FAQ explains <a class="reference external" href="https://docs.python.org/3/faq/windows.html#how-do-i-run-a-python-program-under-windows">how to run a Python program under Windows</a>.</p> </li> <li><p>Usually, <a class="reference external" href="https://pypi.org/project/pip/">pip</a> is automatically installed if you are using Python downloaded from <a class="reference external" href="https://python.org">https://python.org</a>. If not, see the <a class="reference external" href="https://pip.pypa.io/en/stable/installation/">pip documentation</a>.</p></li> <li><p>The command window should recognise the word <span class="docutils literal">py</span> as an instruction to start the interpreter, e.g.</p> <blockquote> <p>py -m pip install docutils</p> </blockquote> <p>If this does not work, you may have to specify the full path to the Python executable.</p> </li> </ul> </section> </section> <section id="usage"> <h2><a class="toc-backref" href="#toc-entry-8" role="doc-backlink">Usage</a><a class="self-link" title="link to this section" href="#usage"></a></h2> <p>Start the "docutils" command line application with:</p> <pre class="literal-block">docutils [options] [<source> [<destination>]]</pre> <p>The default action is to convert a <a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> document to HTML5, for example:</p> <pre class="literal-block">docutils test.rst test.html</pre> <p>Read the <span class="docutils literal"><span class="pre">--help</span></span> option output for details on options and arguments and <a class="reference external" href="docs/user/tools.html">Docutils Front-End Tools</a> for the full documentation of the various tools.</p> <p>For programmatic use of the <cite>docutils</cite> Python package, read the <a class="reference external" href="/docs/index.html#api-reference-material-for-client-developers">API Reference Material</a> and the source code. Remaining questions may be answered in the <a class="reference external" href="/docs/index.html">Docutils Project Documentation</a> or the <a class="reference external" href="docs/user/mailing-lists.html#docutils-users">Docutils-users</a> mailing list.</p> <p>Contributions are welcome!</p> </section> <section id="project-files-directories"> <h2><a class="toc-backref" href="#toc-entry-9" role="doc-backlink">Project Files & Directories</a><a class="self-link" title="link to this section" href="#project-files-directories"></a></h2> <ul class="simple"> <li><p>README.rst: You're reading it.</p></li> <li><p>COPYING.rst: Public Domain Dedication and copyright details for non-public-domain files (most are PD).</p></li> <li><p>FAQ.rst: Frequently Asked Questions (with answers!).</p></li> <li><p>RELEASE-NOTES.rst: Summary of the major changes in recent releases.</p></li> <li><p>HISTORY.rst: A detailed change log, for the current and all previous project releases.</p></li> <li><p>BUGS.rst: Known bugs, and how to report a bug.</p></li> <li><p>THANKS.rst: List of contributors.</p></li> <li><p>pyproject.toml: Project metadata. See "Installation" above.</p></li> <li><p>docutils: The project source directory, installed as a Python package.</p></li> <li><p>docs: The project documentation directory. Read <span class="docutils literal">docs/index.rst</span> for an overview.</p></li> <li><p>docs/user: The project user documentation directory. Contains the following documents, among others:</p> <ul> <li><p>docs/user/tools.rst: Docutils Front-End Tools</p></li> <li><p>docs/user/latex.rst: Docutils LaTeX Writer</p></li> <li><p>docs/user/rst/quickstart.rst: A ReStructuredText Primer</p></li> <li><p>docs/user/rst/quickref.html: Quick reStructuredText (HTML only)</p></li> </ul> </li> <li><p>docs/ref: The project reference directory. <span class="docutils literal">docs/ref/rst/restructuredtext.rst</span> is the reStructuredText reference.</p></li> <li><p>licenses: Directory containing copies of license files for non-public-domain files.</p></li> <li><p>tools: Directory for Docutils front-end tools. See <span class="docutils literal">docs/user/tools.rst</span> for documentation.</p></li> <li><p>test: Unit tests. Not required to use the software, but very useful if you're planning to modify it. See <a class="reference internal" href="#running-the-test-suite">Running the Test Suite</a> below.</p></li> </ul> </section> <section id="development-version"> <h2><a class="toc-backref" href="#toc-entry-10" role="doc-backlink">Development version</a><a class="self-link" title="link to this section" href="#development-version"></a></h2> <p>While we are trying to follow a "release early & often" policy, features are added frequently. We recommend using a current snapshot or a working copy of the repository.</p> <dl> <dt>Repository check-out:</dt> <dd><p>To keep up to date on the latest developments, use a <a class="reference external" href="docs/dev/repository.html#checking-out-the-repository">working copy</a> of the <a class="reference external" href="docs/dev/repository.html">Docutils version repository</a>.</p> </dd> <dt>Snapshots:</dt> <dd><p>To get a repository <span class="target" id="snapshot">snapshot</span>, go to <a class="reference external" href="https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/">https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/</a> and click the download snapshot button.</p> <p>Unpack in a temporary directory, <strong>not</strong> directly in Python's <span class="docutils literal"><span class="pre">site-packages</span></span>.</p> </dd> </dl> <p>See the <a class="reference internal" href="#installation">Installation</a> instructions above.</p> </section> <section id="converting-the-documentation"> <h2><a class="toc-backref" href="#toc-entry-11" role="doc-backlink">Converting the documentation</a><a class="self-link" title="link to this section" href="#converting-the-documentation"></a></h2> <p>After unpacking and installing the Docutils package, the following shell commands will generate HTML for all included documentation:</p> <pre class="literal-block">cd <archive_directory_path> tools/buildhtml.py .</pre> <p>On Windows systems, type:</p> <pre class="literal-block">cd <archive_directory_path> py tools\buildhtml.py ..</pre> <p>The final directory name of the <span class="docutils literal"><archive_directory_path></span> is "docutils" for snapshots. For official releases, the directory may be called "docutils-X.Y.Z", where "X.Y.Z" is the release version.</p> <p>Some files may generate system messages (warnings and errors). The <span class="docutils literal">docs/user/rst/demo.rst</span> file (under the archive directory) contains five intentional errors. (They test the error reporting mechanism!)</p> </section> <section id="running-the-test-suite"> <h2><a class="toc-backref" href="#toc-entry-12" role="doc-backlink">Running the Test Suite</a><a class="self-link" title="link to this section" href="#running-the-test-suite"></a></h2> <p>The test suite is documented in <a class="reference external" href="https://docutils.sourceforge.io/docs/dev/testing.html">Docutils Testing</a> (docs/dev/testing.rst).</p> <p>To run the entire test suite, open a shell and use the following commands:</p> <pre class="literal-block">cd <archive_directory_path>/test ./alltests.py</pre> <p>Under Windows, type:</p> <pre class="literal-block">cd <archive_directory_path>\test python alltests.py</pre> <p>You should see a long line of periods, one for each test, and then a summary like this:</p> <pre class="literal-block">Ran 1744 tests in 5.859s OK (skipped=1) Elapsed time: 6.235 seconds</pre> <p>The number of tests will grow over time, and the times reported will depend on the computer running the tests. Some test are skipped, if optional dependencies (<a class="reference internal" href="#recommendations">recommendations</a>) are missing. The difference between the two times represents the time required to set up the tests (import modules, create data structures, etc.).</p> <p>A copy of the test output is written to the file <span class="docutils literal">alltests.out</span>.</p> <p>If any of the tests fail, please <a class="reference external" href="https://sourceforge.net/p/docutils/bugs/">open a bug report</a> or <a class="reference external" href="mailto:docutils-users@lists.sourceforge.net?subject=Test%20suite%20failure">send an email</a> (see <a class="reference external" href="BUGS.html">Bugs</a>). Please include all relevant output, information about your operating system, Python version, and Docutils version. To see the Docutils version, look at the test output or use</p> <pre class="literal-block">docutils --version</pre> </section> <section id="getting-help"> <h2><a class="toc-backref" href="#toc-entry-13" role="doc-backlink">Getting Help</a><a class="self-link" title="link to this section" href="#getting-help"></a></h2> <p>All documentation can be reached from the <a class="reference external" href="docs/index.html">Project Documentation Overview</a>.</p> <p>The SourceForge <a class="reference external" href="https://sourceforge.net/p/docutils">project page</a> has links to the tracker, mailing lists, and code repository.</p> <p>If you have further questions or need assistance with Docutils or reStructuredText, please post a message to the <a class="reference external" href="docs/user/mailing-lists.html#docutils-users">Docutils-users</a> mailing list.</p>  </section> </main> <footer> <p><a class="reference external" href="README.rst">View document source</a>. Generated on: 2024-10-24 18:13 UTC. Generated by <a class="reference external" href="https://docutils.sourceforge.io/">Docutils</a> from <a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source. </p> </footer> </body> </html>