网页 综合 更新时间 2026-11-17 02:30:29

reStructuredText Primer — Sphinx documentation

自动蜘蛛 www.sphinx-doc.org 正文约 4665 字
reStructuredText is the default plaintext markup language used by Sphinx. This section is a brief introduction to reStructuredText (reST) concepts and syntax, intended to provide authors with enough information to author documents productively. Since reStructuredText was designed to be a simple, unobtrusive markup language, this will not take too long.
The authoritative reStructuredText User Documentation. The “ref” links in this document link to the description of the individual constructs in the reStructuredText reference.
The paragraph (ref) is the most basic block in a reStructuredText document. Paragraphs are simply chunks of text separated by one or more blank lines. As in Python, indentation is significant in reStructuredText, so all lines of the same paragraph must be left-aligned to the same level of indentation.
The standard reStructuredText inline markup is quite simple: use
one asterisk: *text* for emphasis (italics),
two asterisks: **text** for strong emphasis (boldface), and
backquotes: ``text`` for code samples.
If asterisks or backquotes appear in running text and could be confused with inline markup delimiters, they have to be escaped with a backslash.
Be aware of some restrictions of this markup:
it may not be nested,
content may not start or end with whitespace: * text* is wrong,
it must be separated from surrounding text by non-word characters. Use a backslash escaped space to work around that: thisis\ *one*\ word.
These restrictions may be lifted in future versions of the docutils.
It is also possible to replace or expand upon some of this inline markup with roles. Refer to Roles for more information.
List markup (ref) is natural: just place an asterisk at the start of a paragraph and indent properly. The same goes for numbered lists; they can also be autonumbered using a # sign:
Nested lists are possible, but be aware that they must be separated from the parent list items by blank lines:
Definition lists (ref) are created as follows:
Note that the term cannot have more than one line of text.
Quoted paragraphs (ref) are created by just indenting them more than the surrounding paragraphs.
Line blocks (ref) are a way of preserving line breaks:
There are also several more special blocks available:
field lists (ref, with caveats noted in Field Lists)
quoted literal blocks (ref)
doctest blocks (ref)
Literal code blocks (ref) are introduced by ending a paragraph with the special marker ::. The literal block must be indented (and, like all paragraphs, separated from the surrounding ones by blank lines):
The handling of the :: marker is smart:
If it occurs as a paragraph of its own, that paragraph is completely left out of the document.
If it is preceded by whitespace, the marker is removed.
If it is preceded by non-whitespace, the marker is replaced by a single colon.
That way, the second sentence in the above example’s first paragraph would be rendered as “The next paragraph is a code sample:”.
Code highlighting can be enabled for these literal blocks on a document-wide basis using the highlight directive and on a project-wide basis using the highlight_language configuration option. The code-block directive can be used to set highlighting on a block-by-block basis. These directives are discussed later.
Doctest blocks (ref) are interactive Python sessions cut-and-pasted into docstrings. They do not require the literal blocks syntax. The doctest block must end with a blank line and should not end with an unused prompt:
For grid tables (ref), you have to “paint” the cell grid yourself. They look like this:
Simple tables (ref) are easier to write, but limited: they must contain more than one row, and the first column cells cannot contain multiple lines. They look like this:
Two more syntaxes are supported: CSV tables and List tables. They use an explicit markup block. Refer to Tables for more information.
URLs and email addresses in text are automatically linked and do not need explicit markup at all. For example, https://domain.invalid/ is written with no special markup in the source of this document, and is recognised as an external hyperlink.
To create text with a link, the best approach is generally to put the URL below the paragraph as follows (ref):
This keeps the paragraph more readable in source code.
Alternatively, you can embed the URL within the prose for an ‘inline link’. This can lead to longer lines, but has the benefit of keeping the link text and the URL pointed to in the same place. This uses the following syntax: `Link text <https://domain.invalid/>`__ (ref).
There must be a space between the link text and the opening angle bracket (’<’) for the URL.
访问原文 返回搜索 https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
本页为82搜索生成的网页快照,内容来自站内索引;演示数据的原文链接仅作示例。