/usr/share/doc/docutils-doc/README.html is in docutils-doc 0.14+dfsg-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 | <?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.14: http://docutils.sourceforge.net/" />
<title>README: Docutils 0.14</title>
<meta name="author" content="David Goodger" />
<meta name="date" content="2017-08-03" />
<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-14">
<h1 class="title">README: Docutils 0.14</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>2017-08-03</td></tr>
<tr class="web-site field"><th class="docinfo-name">Web site:</th><td class="field-body"><a class="reference external" href="http://docutils.sourceforge.net/">http://docutils.sourceforge.net/</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 first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#quick-start-on-debian-systems" id="id1">Quick-Start on Debian systems</a></li>
<li><a class="reference internal" href="#quick-start-on-other-systems" id="id2">Quick-Start on other systems</a></li>
<li><a class="reference internal" href="#purpose" id="id3">Purpose</a></li>
<li><a class="reference internal" href="#releases-snapshots" id="id4">Releases & Snapshots</a></li>
<li><a class="reference internal" href="#requirements" id="id5">Requirements</a><ul>
<li><a class="reference internal" href="#python-3-compatibility" id="id6">Python 3 compatibility</a></li>
</ul>
</li>
<li><a class="reference internal" href="#project-files-directories" id="id7">Project Files & Directories</a></li>
<li><a class="reference internal" href="#installation" id="id8">Installation</a><ul>
<li><a class="reference internal" href="#gnu-linux-bsds-unix-mac-os-x-etc" id="id9">GNU/Linux, BSDs, Unix, Mac OS X, etc.</a></li>
<li><a class="reference internal" href="#windows" id="id10">Windows</a></li>
</ul>
</li>
<li><a class="reference internal" href="#usage" id="id11">Usage</a></li>
<li><a class="reference internal" href="#converting-the-documentation" id="id12">Converting the documentation</a></li>
<li><a class="reference internal" href="#running-the-test-suite" id="id13">Running the Test Suite</a></li>
<li><a class="reference internal" href="#getting-help" id="id14">Getting Help</a></li>
</ul>
</div>
<div class="section" id="quick-start-on-debian-systems">
<h1><a class="toc-backref" href="#id1">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/python-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="#id2">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 Python (version 2.4 or later), available from</p>
<blockquote>
<p><a class="reference external" href="http://www.python.org/">http://www.python.org/</a></p>
</blockquote>
<p>See <a class="reference internal" href="#requirements">Requirements</a> below for details.</p>
</li>
<li><p class="first">Use the latest Docutils code. Get the code from the <a class="reference external" href="docs/dev/repository.html">Subversion
repository</a> or from the snapshot:</p>
<blockquote>
<p><a class="reference external" href="http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/docutils/?view=tar">http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/docutils/?view=tar</a></p>
</blockquote>
<p>See <a class="reference internal" href="#releases-snapshots">Releases & Snapshots</a> below for details.</p>
</li>
<li><p class="first">Unpack the tarball in a temporary directory (<strong>not</strong> directly in
Python's <tt class="docutils literal"><span class="pre">site-packages</span></tt>), go to the directory created by expanding
the archive, and run <tt class="docutils literal">setup.py install</tt>. On
Windows systems it may be sufficient to double-click <tt class="docutils literal">install.py</tt>.</p>
<p>See <a class="reference internal" href="#installation">Installation</a> below for details.</p>
</li>
<li><p class="first">Use the front-end scripts 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="#id3">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,
XML, and LaTeX. Support for the following sources has been
implemented:</p>
<ul class="simple">
<li>Standalone files.</li>
<li><a class="reference external" href="http://www.python.org/peps/pep-0012.html">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="releases-snapshots">
<h1><a class="toc-backref" href="#id4">Releases & Snapshots</a></h1>
<p>While we are trying to follow a "release early & often" policy,
features are added frequently. Since the code in the Subversion
repository is usually in a bug-free state, we recommend that you use
a current snapshot.</p>
<p>To get a snapshot, go to the code page and click the download snapshot
button:</p>
<ul class="simple">
<li>Docutils code, documentation, front-end tools, and tests:
<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></li>
<li>Sandbox (experimental, contributed code):
<a class="reference external" href="https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/sandbox/">https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/sandbox/</a></li>
</ul>
<p>To keep up to date on the latest developments, download fresh copies of
the snapshots regularly or use a working copy of the
<a class="reference external" href="docs/dev/repository.html">Subversion repository</a>.</p>
</div>
<div class="section" id="requirements">
<h1><a class="toc-backref" href="#id5">Requirements</a></h1>
<p>To run the code, <a class="reference external" href="http://www.python.org/.">Python</a> must be installed.
Docutils is compatible with Python versions from 2.4 up to 2.7 and
versions 3.1 to 3.5 (cf. <a class="reference internal" href="#python-3-compatibility">Python 3 compatibility</a>).</p>
<p>Docutils uses the following packages for enhanced functionality, if they are
installed:</p>
<ul class="simple">
<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="http://pygments.org/">Pygments</a> syntax highlighter is used for content of <cite>code</cite>
directives and roles.</li>
</ul>
<div class="section" id="python-3-compatibility">
<h2><a class="toc-backref" href="#id6">Python 3 compatibility</a></h2>
<p>The Docutils codebase is written for Python 2 and uses "on-demand"
translation for <a class="reference external" href="http://docs.python.org/py3k/howto/pyporting.html">porting to Python 3</a>.</p>
<ul class="simple">
<li>The <cite>setup.py</cite> script generates Python 3 compatible sources in
<tt class="docutils literal">build/</tt> and tests in <tt class="docutils literal">tests3/</tt> sub-directories during
<a class="reference internal" href="#installation">installation</a> with Python 3.</li>
<li>The scripts in the <tt class="docutils literal">tools/</tt> sub-directory work with all supported
Python versions without conversion.</li>
<li>To convert the sources without installing (e.g. for testing), run
<tt class="docutils literal">python3 setup.py build</tt>.</li>
<li>When editing the source, do changes on the Python 2 versions of the
files and re-run the build command.</li>
</ul>
</div>
</div>
<div class="section" id="project-files-directories">
<h1><a class="toc-backref" href="#id7">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>
<p>Generated directories when installing under Python 3:</p>
<ul class="simple">
<li>build: Converted sources.</li>
<li>test3: Converted tests.</li>
</ul>
</div>
<div class="section" id="installation">
<h1><a class="toc-backref" href="#id8">Installation</a></h1>
<p>The first step is to expand the <tt class="docutils literal">.tgz</tt> archive in a temporary
directory (<strong>not</strong> directly in Python's <tt class="docutils literal"><span class="pre">site-packages</span></tt>). It
contains a distutils setup file "setup.py". OS-specific installation
instructions follow.</p>
<div class="section" id="gnu-linux-bsds-unix-mac-os-x-etc">
<h2><a class="toc-backref" href="#id9">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 created by expanding the archive:</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)
python 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.1 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="http://en.wikipedia.org/wiki/Shebang_%28Unix%29">shebang line</a> of the <tt class="docutils literal"><span class="pre">rst2*.py</span></tt> wrapper scripts.</p>
</li>
</ol>
</div>
<div class="section" id="windows">
<h2><a class="toc-backref" href="#id10">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>
<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>
</div>
<div class="section" id="usage">
<h1><a class="toc-backref" href="#id11">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 "--help" option to
the front-end tools for details on options and arguments. See
Docutils Front-End Tools (<tt class="docutils literal">docs/user/tools.txt</tt>) 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="converting-the-documentation">
<h1><a class="toc-backref" href="#id12">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="#id13">Running the Test Suite</a></h1>
<p>The test suite is documented in <a class="reference external" href="http://docutils.sourceforge.net/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>For testing with Python 3 use the converted test suite:</p>
<pre class="literal-block">
cd <archive_directory_path>/test3
python3 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>If any of the tests fail, please <a class="reference external" href="http://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, use one of the <tt class="docutils literal">rst2*</tt> front ends or <tt class="docutils literal">tools/quicktest.py</tt>
with the <tt class="docutils literal"><span class="pre">--version</span></tt> option, e.g.:</p>
<pre class="literal-block">
cd ../tools
./quicktest.py --version
</pre>
<p>Windows users type these commands:</p>
<pre class="literal-block">
cd ..\tools
python quicktest.py --version
</pre>
</div>
<div class="section" id="getting-help">
<h1><a class="toc-backref" href="#id14">Getting Help</a></h1>
<p>If you have 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>
|