| 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 : /usr/share/doc/docutils-doc/docs/dev/ |
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>Docutils Distributor's Guide</title> <meta name="author" content="Lea Wiemann" /> <meta name="date" content="2022-04-02" /> <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="header"> <a class="reference external" href="https://docutils.sourceforge.io">Docutils</a> | <a class="reference external" href="../index.html">Overview</a> | <a class="reference external" href="../index.html#project-fundamentals">About</a> | <a class="reference external" href="../index.html#user">Users</a> | <a class="reference external" href="../index.html#ref">Reference</a> | <a class="reference external" href="../index.html#howto">Developers</a> <hr class="header"/> </div> <div class="document" id="docutils-distributor-s-guide"> <h1 class="title"><a class="reference external" href="https://docutils.sourceforge.io/">Docutils</a> Distributor's Guide</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>Lea Wiemann</td></tr> <tr><th class="docinfo-name">Contact:</th> <td><a class="first last reference external" href="mailto:docutils-develop@lists.sourceforge.net">docutils-develop@lists.sourceforge.net</a></td></tr> <tr><th class="docinfo-name">Revision:</th> <td>9051</td></tr> <tr><th class="docinfo-name">Date:</th> <td>2022-04-02</td></tr> <tr><th class="docinfo-name">Copyright:</th> <td>This document has been placed in the public domain.</td></tr> </tbody> </table> <!-- Minimal menu bar for inclusion in documentation sources in ``docutils/docs/*/`` sub-diretories. Attention: this is not a standalone document. --> <div class="contents topic" id="contents"> <p class="topic-title">Contents</p> <ul class="simple"> <li><a class="reference internal" href="#dependencies" id="toc-entry-1">Dependencies</a></li> <li><a class="reference internal" href="#python-files" id="toc-entry-2">Python Files</a></li> <li><a class="reference internal" href="#executables" id="toc-entry-3">Executables</a></li> <li><a class="reference internal" href="#documentation" id="toc-entry-4">Documentation</a><ul> <li><a class="reference internal" href="#removing-the-txt-files" id="toc-entry-5">Removing the <tt class="docutils literal">.txt</tt> Files</a></li> </ul> </li> <li><a class="reference internal" href="#other-files" id="toc-entry-6">Other Files</a></li> <li><a class="reference internal" href="#configuration-file" id="toc-entry-7">Configuration File</a></li> <li><a class="reference internal" href="#tests" id="toc-entry-8">Tests</a></li> </ul> </div> <p>This document describes how to create packages of Docutils (e.g. for shipping with a Linux distribution). If you have any questions, please direct them to the <a class="reference external" href="../user/mailing-lists.html#docutils-develop">Docutils-develop</a> mailing list.</p> <p>First, please download the most current <a class="reference external" href="https://docutils.sourceforge.io/#download">release tarball</a> and unpack it.</p> <div class="section" id="dependencies"> <h1><a class="toc-backref" href="#toc-entry-1">Dependencies</a></h1> <p>Docutils has the following dependencies:</p> <ul class="simple"> <li>Python 3.7 or later is required. Use ">= Python 3.7" in the dependencies.</li> <li>Docutils may optionally make use of the PIL (<a class="reference external" href="https://en.wikipedia.org/wiki/Python_Imaging_Library">Python Imaging Library</a> or <a class="reference external" href="https://pypi.org/project/Pillow/">Pillow</a>). If PIL is present, it is automatically detected by Docutils.</li> <li>Docutils recommends the <a class="reference external" href="https://pygments.org/">Pygments</a> syntax hightlighter. If available, it is used for highlighting the content of <a class="reference external" href="../ref/rst/directives.html#code">code directives</a> and roles as well as included source code files (with the "code" option to the <a class="reference external" href="../ref/rst/directives.html#include">include</a> directive).</li> <li>Docutils can use the <a class="reference external" href="https://pypi.org/project/recommonmark/">recommonmark</a> parser to parse input in the Markdown format (new in 0.17).</li> </ul> </div> <div class="section" id="python-files"> <h1><a class="toc-backref" href="#toc-entry-2">Python Files</a></h1> <p>The Docutils Python files must be installed into the <tt class="docutils literal"><span class="pre">site-packages/</span></tt> directory of Python. Running <tt class="docutils literal">python setup.py install</tt> should do the trick, but if you want to place the files yourself, you can just install the <tt class="docutils literal">docutils/</tt> directory of the Docutils tarball to <tt class="docutils literal"><span class="pre">/usr/lib/python/site-packages/docutils/</span></tt>. In this case you should also compile the Python files to <tt class="docutils literal">.pyc</tt> and/or <tt class="docutils literal">.pyo</tt> files so that Docutils doesn't need to be recompiled every time it's executed.</p> </div> <div class="section" id="executables"> <h1><a class="toc-backref" href="#toc-entry-3">Executables</a></h1> <p>The executable front-end tools are located in the <tt class="docutils literal">tools/</tt> directory of the Docutils tarball.</p> <p>The <tt class="docutils literal"><span class="pre">rst2*.py</span></tt> tools are intended for end-users. You should install them to <tt class="docutils literal">/usr/bin/</tt>. You do not need to change the names (e.g. to <tt class="docutils literal"><span class="pre">docutils-rst2html.py</span></tt>) because the <tt class="docutils literal">rst2</tt> prefix is unique.</p> </div> <div class="section" id="documentation"> <h1><a class="toc-backref" href="#toc-entry-4">Documentation</a></h1> <p>The documentation should be generated using <tt class="docutils literal">buildhtml.py</tt>. To generate HTML for all documentation files, go to the <tt class="docutils literal">tools/</tt> directory and run:</p> <pre class="literal-block"> # Place html4css1.css in base directory. cp ../docutils/writers/html4css1/html4css1.css .. ./buildhtml.py --stylesheet-path=../html4css1.css .. </pre> <p>Then install the following files to <tt class="docutils literal">/usr/share/doc/docutils/</tt> (or wherever you install documentation):</p> <ul> <li><p class="first">All <tt class="docutils literal">.html</tt> and <tt class="docutils literal">.txt</tt> files in the base directory.</p> </li> <li><p class="first">The <tt class="docutils literal">docs/</tt> directory.</p> <p>Do not install the contents of the <tt class="docutils literal">docs/</tt> directory directly to <tt class="docutils literal">/usr/share/doc/docutils/</tt>; it's incomplete and would contain invalid references!</p> </li> <li><p class="first">The <tt class="docutils literal">licenses/</tt> directory.</p> </li> <li><p class="first"><tt class="docutils literal">html4css1.css</tt> in the base directory.</p> </li> </ul> <div class="section" id="removing-the-txt-files"> <h2><a class="toc-backref" href="#toc-entry-5">Removing the <tt class="docutils literal">.txt</tt> Files</a></h2> <p>If you are tight with disk space, you can remove all <tt class="docutils literal">.txt</tt> files in the tree except for:</p> <ul class="simple"> <li>those in the <tt class="docutils literal">licenses/</tt> directory because they have not been processed to HTML and</li> <li><tt class="docutils literal">user/rst/cheatsheet.txt</tt> and <tt class="docutils literal">user/rst/demo.txt</tt>, which should be readable in source form.</li> </ul> <p>Before you remove the <tt class="docutils literal">.txt</tt> files you should rerun <tt class="docutils literal">buildhtml.py</tt> with the <tt class="docutils literal"><span class="pre">--no-source-link</span></tt> switch to avoid broken references to the source files.</p> </div> </div> <div class="section" id="other-files"> <h1><a class="toc-backref" href="#toc-entry-6">Other Files</a></h1> <p>You may want to install the Emacs-Lisp files <tt class="docutils literal"><span class="pre">tools/editors/emacs/*.el</span></tt> into the appropriate directory.</p> </div> <div class="section" id="configuration-file"> <h1><a class="toc-backref" href="#toc-entry-7">Configuration File</a></h1> <p>It is possible to have a system-wide configuration file at <tt class="docutils literal">/etc/docutils.conf</tt>. However, this is usually not necessary. You should <em>not</em> install <tt class="docutils literal">tools/docutils.conf</tt> into <tt class="docutils literal">/etc/</tt>.</p> </div> <div class="section" id="tests"> <h1><a class="toc-backref" href="#toc-entry-8">Tests</a></h1> <p>While you probably do not need to ship the tests with your distribution, you can test your package by installing it and then running <tt class="docutils literal">alltests.py</tt> from the <tt class="docutils literal">tests/</tt> directory of the Docutils tarball.</p> <p>For more information on testing, view the <a class="reference external" href="https://docutils.sourceforge.io/docs/dev/testing.html">Docutils Testing</a> page.</p> </div> </div> </body> </html>