A reStructuredText Primer

Author:David Goodger <goodger@python.org>
Date:$Date: 2019-06-20 10:38:53 $
Description:reStructuredText 入门教程

Note

How to be a good software engineer

Structure

This is a paragraph. It’s quite short.

This paragraph will result in an indented block of text, typically used for quoting other text.

This is another one.

Text styles

This is a italics and This is Bold all of this called inline markup

double back-block hello func main() * *no inside the double back-quotes work *

Lists

Lists of items come in three main flavours: enumerated, bulleted and definitions. In all list cases, you may have as many paragraphs, sublists, etc. as you want, as long as the left-hand side of the paragraph or whatever aligns with the first line of text in the list item.

Lists must always start a new paragraph – that is, they must appear after a blank line.

enumerated lists

  1. numbers

  1. upper-case letters and it goes over many lines

    with two paragraphs and all!

  1. lower-case letters
    1. with a sub-list starting at a different number
    2. make sure the numbers are in the correct sequence though!
  1. upper-case roman numerals
  1. lower-case roman numerals
  1. numbers again
  1. and again

bulleted lists

  • a bullet point using “*”
    • a sub-list using “-“
      • yet another sub-list
    • another item

definition lists

what
Definition lists associate a term with a definition.
how
The term is a one-line phrase, and the definition is one or more paragraphs or body elements, indented relative to the term. Blank lines are not allowed between term and definition.

Preformatting(code samples)

An example:

  Whitespace, newlines, blank lines, and all kinds of markup
    (like *this* or \this) is preserved by literal blocks.
Lookie here, I've dropped an indentation level
(but not far enough)

no more example

This is preformatted text, and the
last "::" paragraph is removed

Section

To break longer text up into sections, you use section headers.

These are a single line of text (one or more words) with adornment: an underline alone, or an underline and an overline together, in dashes “-----”, equals “======”, tildes “~~~~~~” or any of the non-alphanumeric characters “= - : ‘ ” ~ ^ _ * + # < >” that you feel comfortable with.

An underline-only adornment is distinct from an overline-and-underline adornment using the same character.

The underline/overline must be at least as long as the title text.

Be consistent, since all sections marked with the same adornment style are deemed to be at the same level:

Line block

A one, two, a one two three four

Half a bee, philosophically,
must, ipso facto, half not be.
But half the bee has got to be,
vis a vis its entity. D’you see?

But can a bee be said to be
or not to be an entire bee,
when half the bee is not a bee,
due to some ancient injury?

Singing…

reStructuredText Directives

Sidebar Title

Optional Sidebar Subtitle

Subsequent indented lines comprise the body of the sidebar, and are interpreted as body elements.

Lend us a couple of bob till Thursday.
I’m absolutely skint.
But I’m expecting a postal order and I can pay you back
as soon as it comes.
Love, Ewan.
\[α_t(i) = P(O_1, O_2, … O_t, q_t = S_i λ)\]

No matter where you go, there you are.

—Buckaroo Banzai

This paragraph might be rendered in a custom way.
Frozen Delights!(csv-table)
Treat Quantity Description
Albatross 2.99 On a stick!
Crunchy Frog 1.49 If we took the bones out, it wouldn’t be crunchy, now would it?
Gannet Ripple 1.99 On a stick!
Frozen Delights!(list-table)
Treat Quantity Description
Albatross 2.99 On a stick!
Crunchy Frog 1.49 If we took the bones out, it wouldn’t be crunchy, now would it?
Gannet Ripple 1.99 On a stick!

The rm command is very dangerous. If you are logged in as root and enter

cd /
rm -rf *

you will erase the entire contents of your file system.