| Server IP : 82.148.16.210 / Your IP : 216.73.216.19 Web Server : nginx/1.29.5 System : Linux mail.sarafai.ru 6.1.0-43-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.162-1 (2026-02-08) x86_64 User : root ( 0) PHP Version : 7.4.33 Disable Function : pcntl_alarm,pcntl_fork,pcntl_waitpid,pcntl_wait,pcntl_wifexited,pcntl_wifstopped,pcntl_wifsignaled,pcntl_wifcontinued,pcntl_wexitstatus,pcntl_wtermsig,pcntl_wstopsig,pcntl_signal,pcntl_signal_get_handler,pcntl_signal_dispatch,pcntl_get_last_error,pcntl_strerror,pcntl_sigprocmask,pcntl_sigwaitinfo,pcntl_sigtimedwait,pcntl_exec,pcntl_getpriority,pcntl_setpriority,pcntl_async_signals,pcntl_unshare, MySQL : OFF | cURL : ON | WGET : ON | Perl : ON | Python : ON | Sudo : ON | Pkexec : OFF Directory : /proc/746/root/usr/share/doc/python3-docutils/ |
Upload File : |
<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" /> <title>README: Docutils 0.19</title> <meta name="author" content="David Goodger" /> <meta name="date" content="2022-07-05" /> <meta name="copyright" content="This document has been placed in the public domain." /> <link rel="stylesheet" href="css/html4css1.css" type="text/css" /> </head> <body> <div class="document" id="readme-docutils-0-19"> <h1 class="title">README: Docutils 0.19</h1> <table class="docinfo" frame="void" rules="none"> <col class="docinfo-name" /> <col class="docinfo-content" /> <tbody valign="top"> <tr><th class="docinfo-name">Author:</th> <td>David Goodger</td></tr> <tr><th class="docinfo-name">Contact:</th> <td><a class="first last reference external" href="mailto:goodger@python.org">goodger@python.org</a></td></tr> <tr><th class="docinfo-name">Date:</th> <td>2022-07-05</td></tr> <tr class="web-site field"><th class="docinfo-name">Web site:</th><td class="field-body"><a class="reference external" href="https://docutils.sourceforge.io/">https://docutils.sourceforge.io/</a></td> </tr> <tr><th class="docinfo-name">Copyright:</th> <td>This document has been placed in the public domain.</td></tr> </tbody> </table> <div class="contents topic" id="contents"> <p class="topic-title">Contents</p> <ul class="simple"> <li><a class="reference internal" href="#quick-start-on-debian-systems" id="toc-entry-1">Quick-Start on Debian systems</a></li> <li><a class="reference internal" href="#quick-start-on-other-systems" id="toc-entry-2">Quick-Start on other systems</a></li> <li><a class="reference internal" href="#purpose" id="toc-entry-3">Purpose</a></li> <li><a class="reference internal" href="#dependencies" id="toc-entry-4">Dependencies</a><ul> <li><a class="reference internal" href="#optional-dependencies" id="toc-entry-5">Optional Dependencies</a></li> </ul> </li> <li><a class="reference internal" href="#development-version" id="toc-entry-6">Development version</a></li> <li><a class="reference internal" href="#installation" id="toc-entry-7">Installation</a><ul> <li><a class="reference internal" href="#gnu-linux-bsds-unix-mac-os-x-etc" id="toc-entry-8">GNU/Linux, BSDs, Unix, Mac OS X, etc.</a></li> <li><a class="reference internal" href="#windows" id="toc-entry-9">Windows</a></li> </ul> </li> <li><a class="reference internal" href="#usage" id="toc-entry-10">Usage</a></li> <li><a class="reference internal" href="#project-files-directories" id="toc-entry-11">Project Files & Directories</a></li> <li><a class="reference internal" href="#converting-the-documentation" id="toc-entry-12">Converting the documentation</a></li> <li><a class="reference internal" href="#running-the-test-suite" id="toc-entry-13">Running the Test Suite</a></li> <li><a class="reference internal" href="#getting-help" id="toc-entry-14">Getting Help</a></li> </ul> </div> <div class="section" id="quick-start-on-debian-systems"> <h1><a class="toc-backref" href="#toc-entry-1">Quick-Start on Debian systems</a></h1> <p>The reStructuredText tools are installed in the normal system path by the Debian <tt class="docutils literal"><span class="pre">python-docutils</span></tt> package. To convert reStructuredText to another format, use a shell command like:</p> <pre class="literal-block"> rst2html /usr/share/doc/python3-docutils/FAQ.txt ./FAQ.html </pre> <p>See <a class="reference internal" href="#usage">Usage</a> below for details.</p> </div> <div class="section" id="quick-start-on-other-systems"> <h1><a class="toc-backref" href="#toc-entry-2">Quick-Start on other systems</a></h1> <p>This is for those who want to get up & running quickly.</p> <ol class="arabic"> <li><p class="first">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 class="first">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"> python3 -m pip install docutils </pre> <p>For alternatives and details, see section <a class="reference internal" href="#installation">Installation</a> below.</p> </li> <li><p class="first">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"> rst2html.py FAQ.txt FAQ.html (Unix) python tools/rst2html.py FAQ.txt FAQ.html (Windows) </pre> <p>See <a class="reference internal" href="#usage">Usage</a> below for details.</p> </li> </ol> </div> <div class="section" id="purpose"> <h1><a class="toc-backref" href="#toc-entry-3">Purpose</a></h1> <p>The purpose of the Docutils project is to create 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>Standalone files.</li> <li><a class="reference external" href="https://peps.python.org/pep-0012">PEPs (Python Enhancement Proposals)</a>.</li> </ul> <p>Support for the following sources is planned:</p> <ul class="simple"> <li>Inline documentation from Python modules and packages, extracted with namespace context.</li> <li>Email (RFC-822 headers, quoted excerpts, signatures, MIME parts).</li> <li>Wikis, with global reference lookups of "wiki links".</li> <li>Compound documents, such as multiple chapter files merged into a book.</li> <li>And others as discovered.</li> </ul> </div> <div class="section" id="dependencies"> <h1><a class="toc-backref" href="#toc-entry-4">Dependencies</a></h1> <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>Docutils 0.19 requires Python 3.7 or later.</li> <li>Docutils 0.16 to 0.18 require Python 2.7 or 3.5+.</li> <li>Docutils 0.14 dropped Python 2.4, 2.5, 3.1 and 3.2 support.</li> </ul> <div class="section" id="optional-dependencies"> <h2><a class="toc-backref" href="#toc-entry-5">Optional Dependencies</a></h2> <p>Docutils uses the following packages for enhanced functionality, if they are installed:</p> <ul class="simple"> <li><a class="reference internal" href="#installation">Installation</a> is usually done with <a class="reference external" href="https://pypi.org/project/pip/">pip</a> or <a class="reference external" href="https://pypi.org/project/setuptools/">setuptools</a>.</li> <li>The <a class="reference external" href="http://www.pythonware.com/products/pil/">Python Imaging Library</a>, or PIL, is used for some image manipulation operations.</li> <li>The <a class="reference external" href="https://pypi.org/project/Pygments/">Pygments</a> package provides syntax highlight of "code" directives and roles.</li> <li>The <a class="reference external" href="https://pypi.org/project/myst-docutils/">myst</a> or <a class="reference external" href="https://github.com/rtfd/recommonmark">recommonmark</a> parsers can be used to parse input in Markdown format.</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> </div> </div> <div class="section" id="development-version"> <h1><a class="toc-backref" href="#toc-entry-6">Development version</a></h1> <p>While we are trying to follow a "release early & often" policy, features are added frequently. Since the code in the <a class="reference external" href="docs/dev/repository.html">Docutils version repository</a> is usually in a bug-free state, we recommend using a current snapshot or a working copy.</p> <dl class="docutils"> <dt>Snapshots:</dt> <dd>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.</dd> <dt>Repository check-out:</dt> <dd>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>.</dd> </dl> <p>Continue with the <a class="reference internal" href="#installation">Installation</a> instructions below.</p> </div> <div class="section" id="installation"> <h1><a class="toc-backref" href="#toc-entry-7">Installation</a></h1> <ul> <li><p class="first">The simplest way is to 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"> python3 -m pip install docutils </pre> <p>To install a pre-relase, append the option <tt class="docutils literal"><span class="pre">--pre</span></tt>.</p> </li> <li><p class="first">To install a <a class="reference internal" href="#development-version">development version</a> from source with <a class="reference external" href="https://pypi.org/project/setuptools/">setuptools</a>:</p> <ul> <li><p class="first">Go to the directory containing the file <tt class="docutils literal">setup.py</tt>.</p> <p>A <a class="reference internal" href="#snapshot">snapshot</a> must be unpacked in a temporary directory (<strong>not</strong> directly in Python's <tt class="docutils literal"><span class="pre">site-packages</span></tt>) first.</p> </li> <li><p class="first">Run <tt class="docutils literal">setup.py install</tt>. See also OS-specific installation instructions below.</p> </li> </ul> </li> <li><p class="first">For installing "by hand" or in "development mode", see the <a class="reference external" href="docs/dev/repository.html#editable-installs">editable installs</a> section in the <a class="reference external" href="docs/dev/repository.html">Docutils version repository</a> documentation.</p> </li> </ul> <p>Optional steps:</p> <ul class="simple"> <li><a class="reference internal" href="#running-the-test-suite">Running the test suite</a></li> <li><a class="reference internal" href="#converting-the-documentation">Converting the documentation</a></li> </ul> <div class="section" id="gnu-linux-bsds-unix-mac-os-x-etc"> <h2><a class="toc-backref" href="#toc-entry-8">GNU/Linux, BSDs, Unix, Mac OS X, etc.</a></h2> <ol class="arabic"> <li><p class="first">Open a shell.</p> </li> <li><p class="first">Go to the directory containing <tt class="docutils literal">setup.py</tt>:</p> <pre class="literal-block"> cd <archive_directory_path> </pre> </li> <li><p class="first">Install the package (you may need root permissions to complete this step):</p> <pre class="literal-block"> su (enter admin password) python3 setup.py install </pre> <p>If the python executable isn't on your path, you'll have to specify the complete path, such as <tt class="docutils literal">/usr/local/bin/python</tt>.</p> <p>To install for a specific Python version, use this version in the setup call, e.g.</p> <pre class="literal-block"> python3.7 setup.py install </pre> <p>To install for different Python versions, repeat step 3 for every required version. The last installed version will be used in the <a class="reference external" href="https://en.wikipedia.org/wiki/Shebang_%28Unix%29">shebang line</a> of the <a class="reference external" href="docs/user/tools.html">front-end scripts</a>.</p> </li> </ol> </div> <div class="section" id="windows"> <h2><a class="toc-backref" href="#toc-entry-9">Windows</a></h2> <p>Just double-click <tt class="docutils literal">install.py</tt>. If this doesn't work, try the following:</p> <ol class="arabic"> <li><p class="first">Open a DOS Box (Command Shell, MS-DOS Prompt, or whatever they're calling it these days).</p> </li> <li><p class="first">Go to the directory created by expanding the archive:</p> <pre class="literal-block"> cd <archive_directory_path> </pre> </li> <li><p class="first">Install the package:</p> <pre class="literal-block"> <path_to_python.exe>\python setup.py install </pre> <p>To install for a specific python version, specify the Python executable for this version.</p> <p>To install for different Python versions, repeat step 3 for every required version.</p> </li> </ol> </div> </div> <div class="section" id="usage"> <h1><a class="toc-backref" href="#toc-entry-10">Usage</a></h1> <p>There are many front-end tools in the unpacked "tools" subdirectory. Installation under Unix places copies in the PATH. You may want to begin with the "rst2html.py" front-end tool. Most tools take up to two arguments, the source path and destination path, with STDIN and STDOUT being the defaults. Use the <tt class="docutils literal"><span class="pre">--help</span></tt> option to the front-end tools for details on options and arguments. See <a class="reference external" href="docs/user/tools.html">Docutils Front-End Tools</a> for full documentation.</p> <p>On a Debian system the included tools (with the exception of quicktest.py and the development tools in the dev/ directory) are installed into the normal system path, so you can run <tt class="docutils literal">rst2html.py</tt> with a command like:</p> <pre class="literal-block"> rst2html example.txt example.html </pre> <p>The package modules are continually growing and evolving. The <tt class="docutils literal">docutils.statemachine</tt> module is usable independently. It contains extensive inline documentation (in reStructuredText format of course).</p> <p>Contributions are welcome!</p> </div> <div class="section" id="project-files-directories"> <h1><a class="toc-backref" href="#toc-entry-11">Project Files & Directories</a></h1> <ul class="simple"> <li>README.txt: You're reading it.</li> <li>COPYING.txt: Public Domain Dedication and copyright details for non-public-domain files (most are PD).</li> <li>FAQ.txt: Frequently Asked Questions (with answers!).</li> <li>RELEASE-NOTES.txt: Summary of the major changes in recent releases.</li> <li>HISTORY.txt: A detailed change log, for the current and all previous project releases.</li> <li>BUGS.txt: Known bugs, and how to report a bug.</li> <li>THANKS.txt: List of contributors.</li> <li>setup.py: Installation script. See "Installation" below.</li> <li>install.py: Quick & dirty installation script. Just run it. For any kind of customization or help though, setup.py must be used.</li> <li>docutils: The project source directory, installed as a Python package.</li> <li>docs: The project documentation directory. Read <tt class="docutils literal">docs/index.txt</tt> for an overview.</li> <li>docs/user: The project user documentation directory. Contains the following documents, among others:<ul> <li>docs/user/tools.txt: Docutils Front-End Tools</li> <li>docs/user/latex.txt: Docutils LaTeX Writer</li> <li>docs/user/rst/quickstart.txt: A ReStructuredText Primer</li> <li>docs/user/rst/quickref.html: Quick reStructuredText (HTML only)</li> </ul> </li> <li>docs/ref: The project reference directory. <tt class="docutils literal">docs/ref/rst/restructuredtext.txt</tt> is the reStructuredText reference.</li> <li>licenses: Directory containing copies of license files for non-public-domain files.</li> <li>tools: Directory for Docutils front-end tools. See <tt class="docutils literal">docs/user/tools.txt</tt> for documentation.</li> <li>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.</li> </ul> </div> <div class="section" id="converting-the-documentation"> <h1><a class="toc-backref" href="#toc-entry-12">Converting the documentation</a></h1> <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>\tools python buildhtml.py .. </pre> <p>The final directory name of the <tt class="docutils literal"><archive_directory_path></tt> is "docutils" for snapshots. For official releases, the directory may be called "docutils-X.Y.Z", where "X.Y.Z" is the release version. Alternatively:</p> <pre class="literal-block"> cd <archive_directory_path> tools/buildhtml.py --config=tools/docutils.conf (Unix) python tools\buildhtml.py --config=tools\docutils.conf (Windows) </pre> <p>Some files may generate system messages (warnings and errors). The <tt class="docutils literal">docs/user/rst/demo.txt</tt> file (under the archive directory) contains five intentional errors. (They test the error reporting mechanism!)</p> </div> <div class="section" id="running-the-test-suite"> <h1><a class="toc-backref" href="#toc-entry-13">Running the Test Suite</a></h1> <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.txt).</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 1111 tests in 24.653s OK Elapsed time: 26.189 seconds </pre> <p>The number of tests will grow over time, and the times reported will depend on the computer running the tests. 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 <tt class="docutils literal">alltests.out</tt>.</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 one of the <a class="reference external" href="docs/user/tools.html">front-end scripts</a> with the <tt class="docutils literal"><span class="pre">--version</span></tt> option.</p> </div> <div class="section" id="getting-help"> <h1><a class="toc-backref" href="#toc-entry-14">Getting Help</a></h1> <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> <!-- Local Variables: mode: indented-text indent-tabs-mode: nil sentence-end-double-space: t fill-column: 70 End: --> </div> </div> </body> </html>