| Server IP : 82.148.16.210 / Your IP : 216.73.217.46 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 : www-data ( 33) 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/thread-self/root/usr/share/doc/python3-docutils/docs/ref/rst/ |
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>An Introduction to reStructuredText</title> <meta name="author" content="David Goodger" /> <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="an-introduction-to-restructuredtext"> <h1 class="title">An Introduction to reStructuredText</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: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-sub-diretories. Attention: this is not a standalone document. --> <p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. It is useful for inline program documentation (such as Python docstrings), for quickly creating simple web pages, and for standalone documents. <a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> is a proposed revision and reinterpretation of the <a class="reference external" href="https://zopestructuredtext.readthedocs.org/">StructuredText</a> and <a class="reference external" href="https://docutils.sourceforge.io/mirror/setext.html">Setext</a> lightweight markup systems.</p> <p>reStructuredText is designed for extensibility for specific application domains. Its parser is a component of <a class="reference external" href="https://docutils.sourceforge.io/">Docutils</a>.</p> <p>This document defines the <a class="reference internal" href="#goals">goals</a> of reStructuredText and provides a <a class="reference internal" href="#history">history</a> of the project. It is written using the reStructuredText markup, and therefore serves as an example of its use. For a gentle introduction to using reStructuredText, please read <a class="reference external" href="../../user/rst/quickstart.html">A ReStructuredText Primer</a>. The <a class="reference external" href="../../user/rst/quickref.html">Quick reStructuredText</a> user reference is also useful. The <a class="reference external" href="restructuredtext.html">reStructuredText Markup Specification</a> is the definitive reference. There is also an analysis of the <a class="reference external" href="../../dev/rst/problems.html">Problems With StructuredText</a>.</p> <p>ReStructuredText's web page is <a class="reference external" href="https://docutils.sourceforge.io/rst.html">https://docutils.sourceforge.io/rst.html</a>.</p> <div class="section" id="goals"> <h1>Goals</h1> <p>The primary goal of <a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> is to define a markup syntax for use in Python docstrings and other documentation domains, that is readable and simple, yet powerful enough for non-trivial use. The intended purpose of the reStructuredText markup is twofold:</p> <ul class="simple"> <li>the establishment of a set of standard conventions allowing the expression of structure within plaintext, and</li> <li>the conversion of such documents into useful structured data formats.</li> </ul> <p>The secondary goal of reStructuredText is to be accepted by the Python community (by way of being blessed by PythonLabs and the BDFL <a class="footnote-reference" href="#footnote-1" id="footnote-reference-1">[1]</a>) as a standard for Python inline documentation (possibly one of several standards, to account for taste).</p> <table class="docutils footnote" frame="void" id="footnote-1" rules="none"> <colgroup><col class="label" /><col /></colgroup> <tbody valign="top"> <tr><td class="label"><a class="fn-backref" href="#footnote-reference-1">[1]</a></td><td>Python's creator and "Benevolent Dictator For Life", Guido van Rossum.</td></tr> </tbody> </table> <p>To clarify the primary goal, here are specific design goals, in order, beginning with the most important:</p> <ol class="arabic simple"> <li>Readable. The marked-up text must be easy to read without any prior knowledge of the markup language. It should be as easily read in raw form as in processed form.</li> <li>Unobtrusive. The markup that is used should be as simple and unobtrusive as possible. The simplicity of markup constructs should be roughly proportional to their frequency of use. The most common constructs, with natural and obvious markup, should be the simplest and most unobtrusive. Less common constructs, for which there is no natural or obvious markup, should be distinctive.</li> <li>Unambiguous. The rules for markup must not be open for interpretation. For any given input, there should be one and only one possible output (including error output).</li> <li>Unsurprising. Markup constructs should not cause unexpected output upon processing. As a fallback, there must be a way to prevent unwanted markup processing when a markup construct is used in a non-markup context (for example, when documenting the markup syntax itself).</li> <li>Intuitive. Markup should be as obvious and easily remembered as possible, for the author as well as for the reader. Constructs should take their cues from such naturally occurring sources as plaintext email messages, newsgroup postings, and text documentation such as README.txt files.</li> <li>Easy. It should be easy to mark up text using any ordinary text editor.</li> <li>Scalable. The markup should be applicable regardless of the length of the text.</li> <li>Powerful. The markup should provide enough constructs to produce a reasonably rich structured document.</li> <li>Language-neutral. The markup should apply to multiple natural (as well as artificial) languages, not only English.</li> <li>Extensible. The markup should provide a simple syntax and interface for adding more complex general markup, and custom markup.</li> <li>Output-format-neutral. The markup will be appropriate for processing to multiple output formats, and will not be biased toward any particular format.</li> </ol> <p>The design goals above were used as criteria for accepting or rejecting syntax, or selecting between alternatives.</p> <p>It is emphatically <em>not</em> the goal of reStructuredText to define docstring semantics, such as docstring contents or docstring length. These issues are orthogonal to the markup syntax and beyond the scope of this specification.</p> <p>Also, it is not the goal of reStructuredText to maintain compatibility with <a class="reference external" href="https://zopestructuredtext.readthedocs.org/">StructuredText</a> or <a class="reference external" href="https://docutils.sourceforge.io/mirror/setext.html">Setext</a>. reStructuredText shamelessly steals their great ideas and ignores the not-so-great.</p> <p>Author's note:</p> <blockquote> <p>Due to the nature of the problem we're trying to solve (or, perhaps, due to the nature of the proposed solution), the above goals unavoidably conflict. I have tried to extract and distill the wisdom accumulated over the years in the Python <a class="reference external" href="https://www.python.org/sigs/doc-sig/">Doc-SIG</a> mailing list and elsewhere, to come up with a coherent and consistent set of syntax rules, and the above goals by which to measure them.</p> <p>There will inevitably be people who disagree with my particular choices. Some desire finer control over their markup, others prefer less. Some are concerned with very short docstrings, others with full-length documents. This specification is an effort to provide a reasonably rich set of markup constructs in a reasonably simple form, that should satisfy a reasonably large group of reasonable people.</p> <p>David Goodger (<a class="reference external" href="mailto:goodger@python.org">goodger@python.org</a>), 2001-04-20</p> </blockquote> </div> <div class="section" id="history"> <h1>History</h1> <p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a>, the specification, is based on <a class="reference external" href="https://zopestructuredtext.readthedocs.org/">StructuredText</a> and <a class="reference external" href="https://docutils.sourceforge.io/mirror/setext.html">Setext</a>. StructuredText was developed by Jim Fulton of <a class="reference external" href="http://www.zope.com">Zope Corporation</a> (formerly Digital Creations) and first released in 1996. It is now released as a part of the open-source "Z Object Publishing Environment" (<a class="reference external" href="https://www.zope.dev">ZOPE</a>). Ian Feldman's and Tony Sanders' earlier <a class="reference external" href="https://docutils.sourceforge.io/mirror/setext.html">Setext</a> specification was either an influence on StructuredText or, by their similarities, at least evidence of the correctness of this approach.</p> <p>I discovered <a class="reference external" href="https://zopestructuredtext.readthedocs.org/">StructuredText</a> in late 1999 while searching for a way to document the Python modules in one of my projects. Version 1.1 of StructuredText was included in Daniel Larsson's <a class="reference external" href="http://starship.python.net/crew/danilo/pythondoc/">pythondoc</a>. Although I was not able to get pythondoc to work for me, I found StructuredText to be almost ideal for my needs. I joined the Python <a class="reference external" href="https://www.python.org/sigs/doc-sig/">Doc-SIG</a> (Documentation Special Interest Group) mailing list and found an ongoing discussion of the shortcomings of the StructuredText "standard". This discussion has been going on since the inception of the mailing list in 1996, and possibly predates it.</p> <p>I decided to modify the original module with my own extensions and some suggested by the Doc-SIG members. I soon realized that the module was not written with extension in mind, so I embarked upon a general reworking, including adapting it to the "re" regular expression module (the original inspiration for the name of this project). Soon after I completed the modifications, I discovered that StructuredText.py was up to version 1.23 in the ZOPE distribution. Implementing the new syntax extensions from version 1.23 proved to be an exercise in frustration, as the complexity of the module had become overwhelming.</p> <p>In 2000, development on StructuredTextNG ("Next Generation") began at <a class="reference external" href="http://www.zope.com">Zope Corporation</a> (then Digital Creations). It seems to have many improvements, but still suffers from many of the problems of classic StructuredText.</p> <p>I decided that a complete rewrite was in order, and even started a <a class="reference external" href="http://structuredtext.sourceforge.net/">reStructuredText SourceForge project</a> (now inactive). My motivations (the "itches" I aim to "scratch") are as follows:</p> <ul class="simple"> <li>I need a standard format for inline documentation of the programs I write. This inline documentation has to be convertible to other useful formats, such as HTML. I believe many others have the same need.</li> <li>I believe in the Setext/StructuredText idea and want to help formalize the standard. However, I feel the current specifications and implementations have flaws that desperately need fixing.</li> <li>reStructuredText could form part of the foundation for a documentation extraction and processing system, greatly benefitting Python. But it is only a part, not the whole. reStructuredText is a markup language specification and a reference parser implementation, but it does not aspire to be the entire system. I don't want reStructuredText or a hypothetical Python documentation processor to die stillborn because of over-ambition.</li> <li>Most of all, I want to help ease the documentation chore, the bane of many a programmer.</li> </ul> <p>Unfortunately I was sidetracked and stopped working on this project. In November 2000 I made the time to enumerate the problems of StructuredText and possible solutions, and complete the first draft of a specification. This first draft was posted to the Doc-SIG in three parts:</p> <ul class="simple"> <li><a class="reference external" href="https://mail.python.org/pipermail/doc-sig/2000-November/001239.html">A Plan for Structured Text</a></li> <li><a class="reference external" href="https://mail.python.org/pipermail/doc-sig/2000-November/001240.html">Problems With StructuredText</a></li> <li><a class="reference external" href="https://mail.python.org/pipermail/doc-sig/2000-November/001241.html">reStructuredText: Revised Structured Text Specification</a></li> </ul> <p>In March 2001 a flurry of activity on the Doc-SIG spurred me to further revise and refine my specification, the result of which you are now reading. An offshoot of the reStructuredText project has been the realization that a single markup scheme, no matter how well thought out, may not be enough. In order to tame the endless debates on Doc-SIG, a flexible <a class="reference external" href="../../peps/pep-0256.html">Docstring Processing System framework</a> needed to be constructed. This framework has become the more important of the two projects; <a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> has found its place as one possible choice for a single component of the larger framework.</p> <p>The project web site and the first project release were rolled out in June 2001, including posting the second draft of the spec <a class="footnote-reference" href="#spec-2" id="footnote-reference-2">[2]</a> and the first draft of PEPs 256, 257, and 258 <a class="footnote-reference" href="#peps-1" id="footnote-reference-3">[3]</a> to the Doc-SIG. These documents and the project implementation proceeded to evolve at a rapid pace. Implementation history details can be found in the <a class="reference external" href="../../../HISTORY.html">project history file</a>.</p> <p>In November 2001, the reStructuredText parser was nearing completion. Development of the parser continued with the addition of small convenience features, improvements to the syntax, the filling in of gaps, and bug fixes. After a long holiday break, in early 2002 most development moved over to the other Docutils components, the "Readers", "Writers", and "Transforms". A "standalone" reader (processes standalone text file documents) was completed in February, and a basic HTML writer (producing HTML 4.01, using CSS-1) was completed in early March.</p> <p><a class="reference external" href="../../peps/pep-0287.html">PEP 287</a>, "reStructuredText Standard Docstring Format", was created to formally propose reStructuredText as a standard format for Python docstrings, PEPs, and other files. It was first posted to <a class="reference external" href="news:comp.lang.python">comp.lang.python</a> and the <a class="reference external" href="https://mail.python.org/pipermail/python-dev/">Python-dev</a> mailing list on 2002-04-02.</p> <p>Version 0.4 of the <a class="reference external" href="http://structuredtext.sourceforge.net/">reStructuredText</a> and <a class="reference external" href="http://docstring.sourceforge.net/">Docstring Processing System</a> projects were released in April 2002. The two projects were immediately merged, renamed to "<a class="reference external" href="https://docutils.sourceforge.io/">Docutils</a>", and a 0.1 release soon followed.</p> <table class="docutils footnote" frame="void" id="spec-2" rules="none"> <colgroup><col class="label" /><col /></colgroup> <tbody valign="top"> <tr><td class="label"><a class="fn-backref" href="#footnote-reference-2">[2]</a></td><td><p class="first">The second draft of the spec:</p> <ul class="simple"> <li><a class="reference external" href="https://mail.python.org/pipermail/doc-sig/2001-June/001858.html">An Introduction to reStructuredText</a></li> <li><a class="reference external" href="https://mail.python.org/pipermail/doc-sig/2001-June/001859.html">Problems With StructuredText</a></li> <li><a class="reference external" href="https://mail.python.org/pipermail/doc-sig/2001-June/001860.html">reStructuredText Markup Specification</a></li> <li><a class="reference external" href="https://mail.python.org/pipermail/doc-sig/2001-June/001861.html">Python Extensions to the reStructuredText Markup Specification</a></li> </ul> </td></tr> </tbody> </table> <table class="docutils footnote" frame="void" id="peps-1" rules="none"> <colgroup><col class="label" /><col /></colgroup> <tbody valign="top"> <tr><td class="label"><a class="fn-backref" href="#footnote-reference-3">[3]</a></td><td><p class="first">First drafts of the PEPs:</p> <ul class="simple"> <li><a class="reference external" href="https://mail.python.org/pipermail/doc-sig/2001-June/001855.html">PEP 256: Docstring Processing System Framework</a></li> <li><a class="reference external" href="https://mail.python.org/pipermail/doc-sig/2001-June/001856.html">PEP 258: DPS Generic Implementation Details</a></li> <li><a class="reference external" href="https://mail.python.org/pipermail/doc-sig/2001-June/001857.html">PEP 257: Docstring Conventions</a></li> </ul> <p>Current working versions of the PEPs can be found in <a class="reference external" href="https://docutils.sourceforge.io/docs/peps/">https://docutils.sourceforge.io/docs/peps/</a>, and official versions can be found in the <a class="reference external" href="https://peps.python.org/">master PEP repository</a>.</p> </td></tr> </tbody> </table> <!-- Local Variables: mode: indented-text indent-tabs-mode: nil sentence-end-double-space: t fill-column: 70 End: --> </div> </div> </body> </html>