Generic items

These are the things that don’t quite fit into other groupings.

Inline Markup

One of the nice things about markup languages is the ability to have inline markup. This makes the presentation much nicer. The bold text shouldn’t be too overbearing. It is very common to have inline code as well. It is important to ensure that the inline code doesn’t have a line height that is greater than the regular prose; otherwise the spacing looks weird.

It is also possible to use explicit roles to do things like a _subscript, a ^superscript, emphasis, strong, and literal.

Hyperlinks

It is a website, so it’ll have hyperlinks like http://www.python.org (inline), or Python [4] (external reference), example (internal reference), Python web site (external hyperlinks with embedded URI), footnote references (manually numbered [1], anonymous auto-numbered [3], labeled auto-numbered [2], or symbolic [*]), citation references ([12]), substitution references (), and inline hyperlink targets (see Targets below for a reference back to here).

reStructuredText has character-level inline markup too. It’s ugly to write, but someone might be using it, so here’s an example: reStructuredText.

It is also possible to link to documented items, such as api_sample.RandomNumberGenerator.

Interpreted text

The default role for “interpreted text” (AKA single backticks) is Title Reference. There are other reference syntaxes as well: PEP 287 and RFC 2822.

If the --pep-references option was supplied, there should be a live link to PEP 258 here.

GUI labels

According to the RST demo, GUI labels (like this label) are a way to indicate that some action is to be taken by the user. Like inline code literals, GUI labels should not run over line height.

Keys / Menu labels

Key-bindings indicate that the reader is to press a button on the keyboard or mouse, for example MMB, ⌘+⇧+M and Shift-MMB. Another useful way is menuselection to show menus: My ‣ Software ‣ Some menu ‣ Some sub menu 1 ‣ Some sub menu 2 ‣ Some sub menu 3

For example, menuselection should break when it is too long to fit on a single line.

Long inline code wrapping

Let’s test wrapping and whitespace significance in inline literals: This is an example of --inline-literal --text, --including some-- strangely--hyphenated-words.  Adjust-the-width-of-your-browser-window to see how the text is wrapped.  -- ---- --------  Now note    the spacing    between the    words of    this sentence    (words should    be grouped    in pairs).

A very long “word”: LoremipsumdolorsitametconsetetursadipscingelitrseddiamnonumyeirmodtemporinviduntutlaboreetdoloremagnaaliquyameratseddiamvoluptuaAtveroeosetaccusametjustoduodoloresetearebum

A very long path: /my/network/directory/where/all/my/fancy/files/reside/but/I/tend/to/hide/them/in/very/long/subdirectories/to/keep/them/very/hard/to/find/even/for/myself.exe

Math

This is a test. Here is an equation: \(X_{0:5} = (X_0, X_1, X_2, X_3, X_4)\). Here is another:

(1)\[\nabla^2 f = \frac{1}{r^2} \frac{\partial}{\partial r} \left( r^2 \frac{\partial f}{\partial r} \right) + \frac{1}{r^2 \sin \theta} \frac{\partial f}{\partial \theta} \left( \sin \theta \, \frac{\partial f}{\partial \theta} \right) + \frac{1}{r^2 \sin^2\theta} \frac{\partial^2 f}{\partial \phi^2}\]

You can add a link to equations like the one above (1) by using :eq:.

Sidebar

Ch’ien / The Creative

Lorem ipsum dolor sit amet consectetur adipisicing elit.

Lorem ipsum dolor sit amet consectetur adipisicing elit.

Lorem ipsum dolor sit amet consectetur adipisicing elit. Accusamus, sunt voluptatum tenetur libero nulla esse veritatis accusantium earum commodi hic voluptatem officia culpa optio atque. Quaerat sed quibusdam ratione nam.

Lorem ipsum dolor sit amet consectetur adipisicing elit. Accusamus, sunt voluptatum tenetur libero nulla esse veritatis accusantium earum commodi hic voluptatem officia culpa optio atque. Quaerat sed quibusdam ratione nam.

Code with Sidebar

A code example

With a sidebar on the right.

Code blocks can also have captions.

print("one")
print("two")
print("three")
print("four")
print("five")
print("six")
print("seven")
print("eight")
print("nine")
print("ten")
print("eleven")
print("twelve")
print("thirteen")
print("fourteen")

References

Footnotes

[1] (1,2)

A footnote contains body elements, consistently indented by at least 3 spaces.

This is the footnote’s second paragraph.

[2] (1,2)

Footnotes may be numbered, either manually (as in [1]) or automatically using a “#”-prefixed label. This footnote has a label so it can be referred to from multiple places, both as a footnote reference ([2]) and as a hyperlink reference (label).

[3]

This footnote is numbered automatically and anonymously using a label of “#” only.

[*]

Footnotes may also use symbols, specified with a “*” label. Here’s a reference to the next footnote: [†].

[†]

This footnote shows the next symbol in the sequence.

Citations

[12] (1,2)

This citation has some code blocks in it, maybe some bold and italics too. Heck, lets put a link to a meta citation [13] too.

[13]

This citation will have one backlink.

Here’s a reference to the above, [12] citation.

Here is another type of citation: citation

Targets

This paragraph is pointed to by the explicit “example” target. A reference can be found under Inline Markup, above. Inline hyperlink targets are also possible.

Section headers are implicit targets, referred to by name. See Targets.

Explicit external targets are interpolated into references such as “Python [4]”.

Targets may be indirect and anonymous. Thus this phrase may also refer to the Targets section.

Target Footnotes

[4] (1,2)

http://www.python.org/

Centered text

You can create a statement with centered text with .. centered::

This is centered text!

Rubric

A rubric is like an informal heading that doesn’t correspond to the document’s structure.

—https://docutils.sourceforge.io/docs/ref/rst/directives.html#rubric

Wikipedia says it is something different:

A rubric is a word or section of text that is traditionally written or printed in red ink for emphasis.

—https://en.wikipedia.org/wiki/Rubric

This is stylized as docutils tells us to stylize it, since it is used for footnote headers (see end of https://docs.python.org/3/reference/lexical_analysis.html)

This is a rubric

Sidebars and Rubrics

Sidebar Title

Optional Subtitle

This is a sidebar. It is for text outside the flow of the main text.

This is a rubric inside a sidebar

Sidebars often appears beside the main text with a border and background color.

Lorem ipsum dolor sit amet consectetur adipisicing elit. Accusamus, sunt voluptatum tenetur libero nulla esse veritatis accusantium earum commodi hic voluptatem officia culpa optio atque. Quaerat sed quibusdam ratione nam.

Lorem ipsum dolor sit amet consectetur adipisicing elit. Accusamus, sunt voluptatum tenetur libero nulla esse veritatis accusantium earum commodi hic voluptatem officia culpa optio atque. Quaerat sed quibusdam ratione nam.

Lorem ipsum dolor sit amet consectetur adipisicing elit. Accusamus, sunt voluptatum tenetur libero nulla esse veritatis accusantium earum commodi hic voluptatem officia culpa optio atque. Quaerat sed quibusdam ratione nam.

Lorem ipsum dolor sit amet consectetur adipisicing elit. Accusamus, sunt voluptatum tenetur libero nulla esse veritatis accusantium earum commodi hic voluptatem officia culpa optio atque. Quaerat sed quibusdam ratione nam.

Download Links

This long long long long long long long long long long long long long long long download link should wrap white-spaces