Sphinx & RST Demo Gallery
This page shows every supported RST and Sphinx element rendered by rich-rst. For each element the raw RST source is shown in a code block, followed by the terminal-styled HTML snapshot produced by rich-rst (Dracula theme, 76-column width).
Inline Markup
Emphasis (italic)
*italicised text*
italicised text
Strong (bold)
**bold text**
bold text
Inline literal (code)
Use ``print()`` to display output.
Use print() to display output.
Hyperlink (external)
Visit `Python <https://www.python.org>`_ for more.
Visit Python for more.
Anonymous hyperlink
See `Rich docs <https://rich.readthedocs.io>`__ for styling.
See Rich docs for styling.
Title reference
Read `The Zen of Python` for inspiration.
Read The Zen of Python for inspiration.
Subscript role
H\ :sub:`2`\ O is water.
H₂O is water.
Superscript role
E = mc\ :sup:`2`
E = mc²
Abbreviation role
:abbr:`RST (reStructuredText)` is a markup language.
RST (reStructuredText) is a markup language.
Keyboard role
Press :kbd:`Ctrl+C` to copy.
Press Ctrl+C to copy.
GUI label role
Click :guilabel:`OK` to confirm.
Click OK to confirm.
File role
Edit :file:`/etc/hosts` with sudo.
Edit /etc/hosts with sudo.
Sample (samp) role
Type :samp:`ping {host}` in the terminal.
Type ping host in the terminal.
Command role
Run :command:`python -m pytest`.
Run python -m pytest.
Program role
:program:`git` is a distributed version control system.
git is a distributed version control system.
All inline styles combined
*Italic*, **bold**, ``literal``, :kbd:`Ctrl+C`,
:guilabel:`OK`, :menuselection:`File --> Open`,
:file:`~/.bashrc`, :command:`ls -la`,
and :sup:`superscript`.
Italic, bold, literal, Ctrl+C, OK, File ▶ Open, ~/.bashrc, ls -la, and
ˢᵘᵖᵉʳˢᶜʳⁱᵖᵗ.
Inline markup in a list
- Use **bold** for important terms
- Use *italic* for emphasis
- Use ``code`` for inline code samples
- Use :kbd:`Enter` for key presses
• Use bold for important terms
• Use italic for emphasis
• Use code for inline code samples
• Use Enter for key presses
PEP reference role
See :pep:`8` for Python style guidelines.
See PEP 8 for Python style guidelines.
RFC reference role
HTTP is described in :rfc:`2616`.
HTTP is described in RFC 2616.
Definition (dfn) role
A :dfn:`docstring` is a string literal that documents a Python object.
A docstring is a string literal that documents a Python object.
CVE reference role
This vulnerability is tracked as :cve:`2024-3094`.
This vulnerability is tracked as CVE-2024-3094.
CWE reference role
This bug is categorized under :cwe:`79`.
This bug is categorized under CWE-79.
PyPI project reference role
Install the package from :pypi:`requests`.
Install the package from requests.
Math role (inline)
The area of a circle is :math:`\pi r^2`.
The area of a circle is π r^2.
Paragraphs and Sections
Plain paragraph
This is a plain paragraph. Paragraphs are separated
by blank lines.
A second paragraph follows here.
This is a plain paragraph. Paragraphs are separated by blank lines.
A second paragraph follows here.
Section headings (all 6 levels)
Level 1 Title
=============
Some body text under level 1.
Level 2 Title
-------------
Some body text under level 2.
Level 3 Title
~~~~~~~~~~~~~
Some body text under level 3.
Level 4 Title
^^^^^^^^^^^^^
Some body text under level 4.
Level 5 Title
"""""""""""""
Some body text under level 5.
Level 6 Title
'''''''''''''
Some body text under level 6.
╔══════════════════════════════════════════════════════════════════════════╗
║ Level 1 Title ║
╚══════════════════════════════════════════════════════════════════════════╝
Some body text under level 1.
╭──────────────────────────────────────────────────────────────────────────╮
│ Level 2 Title │
╰──────────────────────────────────────────────────────────────────────────╯
Some body text under level 2.
Level 3 Title
Some body text under level 3.
Level 4 Title
Some body text under level 4.
Level 5 Title
Some body text under level 5.
Level 6 Title
Some body text under level 6.
Section with overline decoration
##################
Part-level heading
##################
Body text below the overlined heading.
╔══════════════════════════════════════════════════════════════════════════╗
║ Part-level heading ║
╚══════════════════════════════════════════════════════════════════════════╝
Body text below the overlined heading.
Document subtitle
My Document
===========
A subtitle here
---------------
Body text.
╔══════════════════════════════════════════════════════════════════════════╗
║ My Document ║
╚══════════════════════════════════════════════════════════════════════════╝
╭──────────────────────────────────────────────────────────────────────────╮
│ A subtitle here │
╰──────────────────────────────────────────────────────────────────────────╯
Body text.
Multiple paragraphs with transitions
First paragraph before the transition.
----
Second paragraph after the first transition.
----
Third paragraph after the second transition.
First paragraph before the transition.
────────────────────────────────────────────────────────────────────────────
Second paragraph after the first transition.
────────────────────────────────────────────────────────────────────────────
Third paragraph after the second transition.
Lists
Bullet list (dash)
- First item
- Second item
- Third item
• First item
• Second item
• Third item
Bullet list (asterisk)
* Alpha
* Beta
* Gamma
• Alpha
• Beta
• Gamma
Nested bullet list
- Parent item
- Child item one
- Child item two
- Another parent
• Parent item
∘ Child item one
∘ Child item two
• Another parent
Enumerated list (auto-numbered)
#. First step
#. Second step
#. Third step
1. First step
2. Second step
3. Third step
Bullet list (plus sign)
+ One
+ Two
+ Three
• One
• Two
• Three
Deeply nested bullet list
- Level 1 item A
- Level 2 item A1
- Level 3 item A1a
- Level 3 item A1b
- Level 2 item A2
- Level 1 item B
• Level 1 item A
∘ Level 2 item A1
▪ Level 3 item A1a
▪ Level 3 item A1b
∘ Level 2 item A2
• Level 1 item B
Enumerated list (uppercase letters)
A. Alpha
B. Beta
C. Gamma
A. Alpha
B. Beta
C. Gamma
Enumerated list (uppercase roman numerals)
I. Chapter One
II. Chapter Two
III. Chapter Three
I. Chapter One
II. Chapter Two
III. Chapter Three
Mixed ordered and unordered lists
Steps to install:
1. Download the package
- Linux: ``apt install ...``
- macOS: ``brew install ...``
2. Run the installer
3. Verify with ``--version``
Steps to install:
1. Download the package
∘ Linux: apt install ...
∘ macOS: brew install ...
2. Run the installer
3. Verify with --version
Enumerated list (letters)
a. Apple
b. Banana
c. Cherry
a. Apple
b. Banana
c. Cherry
Enumerated list (roman numerals)
i. Item i
ii. Item ii
iii. Item iii
i. Item i
ii. Item ii
iii. Item iii
Definition list
term
Definition of the term.
another term
Its definition spans
multiple lines.
term
Definition of the term.
another term
Its definition spans multiple lines.
Definition list with classifier
term : string
A string-typed term.
count : int
An integer count.
term : string
A string-typed term.
count : int
An integer count.
Field list
:Name: John Doe
:Email: john@example.com
:Role: Developer
┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
┃ Field Name ┃ Field Value ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
│ Name │ John Doe │
├────────────┼──────────────────┤
│ Email │ john@example.com │
├────────────┼──────────────────┤
│ Role │ Developer │
└────────────┴──────────────────┘
Option list
-v, --verbose Enable verbose output.
-o FILE Write output to FILE.
--help Show this help message.
-v, --verbose,
Enable verbose output.
-o FILE
Write output to FILE.
--help
Show this help message.
Horizontal list (hlist)
.. hlist::
:columns: 3
* Alpha
* Beta
* Gamma
* Delta
* Epsilon
* Zeta
Alpha Beta Gamma
Delta Epsilon Zeta
Block Markup
Block quote
Normal paragraph.
This is an indented block quote.
-- Attribution
Normal paragraph.
▌ This is an indented block quote.
— Attribution
Line block
| The first line of a poem.
| The second line continues.
| An indented third line.
The first line of a poem.
The second line continues.
An indented third line.
Doctest block
>>> print("Hello, world!")
Hello, world!
>>> 1 + 1
2
┌───────────────────────────── doctest block ──────────────────────────────┐
│ >>> print("Hello, world!") │
│ Hello, world! │
│ >>> 1 + 1 │
│ 2 │
└──────────────────────────────────────────────────────────────────────────┘
Literal block (indented)
Example code::
def greet(name):
print(f"Hello, {name}!")
Example code:
┌───────────────────────────── text (default) ─────────────────────────────┐
│ def greet(name): │
│ print(f"Hello, {name}!") │
└──────────────────────────────────────────────────────────────────────────┘
Compound directive
.. compound::
The first sentence of a paragraph.
The second paragraph of the compound block,
rendered as a single logical paragraph.
The first sentence of a paragraph.
The second paragraph of the compound block, rendered as a single logical
paragraph.
Parsed literal block
.. parsed-literal::
**Bold** and *italic* inside a literal block.
Also ``code`` here.
┌───────────────────────────── text (default) ─────────────────────────────┐
│ Bold and italic inside a literal block. │
│ Also code here. │
└──────────────────────────────────────────────────────────────────────────┘
Epigraph directive
.. epigraph::
No man is an island,
entire of itself.
-- John Donne
▌ No man is an island, entire of itself.
— John Donne
Highlights directive
.. highlights::
Key takeaways:
- Keep it simple.
- Document everything.
▌ Key takeaways:
▌ • Keep it simple.
▌ • Document everything.
Pull-quote directive
.. pull-quote::
The best way to predict the future
is to invent it.
-- Alan Kay
▌ The best way to predict the future is to invent it.
— Alan Kay
Code Blocks
code-block with language
.. code-block:: python
def factorial(n):
if n == 0:
return 1
return n * factorial(n - 1)
┌───────────────────────────────── python ─────────────────────────────────┐
│ def factorial(n): │
│ if n == 0: │
│ return 1 │
│ return n * factorial(n - 1) │
└──────────────────────────────────────────────────────────────────────────┘
code-block with line numbers
.. code-block:: python
:linenos:
x = 1
y = 2
print(x + y)
┌───────────────────────────────── python ─────────────────────────────────┐
│ 1 x = 1 │
│ 2 y = 2 │
│ 3 print(x + y) │
└──────────────────────────────────────────────────────────────────────────┘
code-block with lineno-start
.. code-block:: python
:linenos:
:lineno-start: 10
x = 1
y = 2
┌───────────────────────────────── python ─────────────────────────────────┐
│ 10 x = 1 │
│ 11 y = 2 │
└──────────────────────────────────────────────────────────────────────────┘
code-block with emphasize-lines
.. code-block:: python
:emphasize-lines: 3,5
def some_function():
interesting = False
print('This line is highlighted.')
print('This one is not...')
print('...but this one is.')
┌───────────────────────────────── python ─────────────────────────────────┐
│ 1 def some_function(): │
│ 2 interesting = False │
│ ❱ 3 print('This line is highlighted.') │
│ 4 print('This one is not...') │
│ ❱ 5 print('...but this one is.') │
└──────────────────────────────────────────────────────────────────────────┘
code-block with name
.. code-block:: python
:name: example-id
x = 1
y = 2
┌────────────────────────── python — example-id ───────────────────────────┐
│ x = 1 │
│ y = 2 │
└──────────────────────────────────────────────────────────────────────────┘
code-block with dedent
.. code-block:: python
:dedent:
def foo():
return 1
┌───────────────────────────────── python ─────────────────────────────────┐
│ def foo(): │
│ return 1 │
└──────────────────────────────────────────────────────────────────────────┘
code-block: bash
.. code-block:: bash
pip install rich-rst
python -m rich_rst README.rst
┌────────────────────────────────── bash ──────────────────────────────────┐
│ pip install rich-rst │
│ python -m rich_rst README.rst │
└──────────────────────────────────────────────────────────────────────────┘
code-block: JSON
.. code-block:: json
{
"name": "rich-rst",
"version": "1.0.0",
"description": "RST renderer for Rich"
}
┌────────────────────────────────── json ──────────────────────────────────┐
│ { │
│ "name": "rich-rst", │
│ "version": "1.0.0", │
│ "description": "RST renderer for Rich" │
│ } │
└──────────────────────────────────────────────────────────────────────────┘
code-block: YAML
.. code-block:: yaml
name: rich-rst
dependencies:
- rich>=10.0
- docutils>=0.17
┌────────────────────────────────── yaml ──────────────────────────────────┐
│ name: rich-rst │
│ dependencies: │
│ - rich>=10.0 │
│ - docutils>=0.17 │
└──────────────────────────────────────────────────────────────────────────┘
sourcecode alias
.. sourcecode:: javascript
const greet = (name) => `Hello, ${name}!`;
console.log(greet('World'));
┌─────────────────────────────── javascript ───────────────────────────────┐
│ const greet = (name) => `Hello, ${name}!`; │
│ console.log(greet('World')); │
└──────────────────────────────────────────────────────────────────────────┘
code alias (no language)
.. code::
plain text block
no syntax highlighting
┌───────────────────────────── text (default) ─────────────────────────────┐
│ plain text block │
│ no syntax highlighting │
└──────────────────────────────────────────────────────────────────────────┘
code-block: C
.. code-block:: c
#include <stdio.h>
int main(void) {
printf("Hello, World!\n");
return 0;
}
┌─────────────────────────────────── c ────────────────────────────────────┐
│ #include <stdio.h> │
│ │
│ int main(void) { │
│ printf("Hello, World!\n"); │
│ return 0; │
│ } │
└──────────────────────────────────────────────────────────────────────────┘
code-block: Java
.. code-block:: java
public class Hello {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
┌────────────────────────────────── java ──────────────────────────────────┐
│ public class Hello { │
│ public static void main(String[] args) { │
│ System.out.println("Hello, World!"); │
│ } │
│ } │
└──────────────────────────────────────────────────────────────────────────┘
code-block: TypeScript
.. code-block:: typescript
function greet(name: string): string {
return `Hello, ${name}!`;
}
console.log(greet("World"));
┌─────────────────────────────── typescript ───────────────────────────────┐
│ function greet(name: string): string { │
│ return `Hello, ${name}!`; │
│ } │
│ console.log(greet("World")); │
└──────────────────────────────────────────────────────────────────────────┘
code-block: SQL
.. code-block:: sql
SELECT name, email
FROM users
WHERE active = TRUE
ORDER BY name ASC
LIMIT 10;
┌────────────────────────────────── sql ───────────────────────────────────┐
│ SELECT name, email │
│ FROM users │
│ WHERE active = TRUE │
│ ORDER BY name ASC │
│ LIMIT 10; │
└──────────────────────────────────────────────────────────────────────────┘
code-block: HTML
.. code-block:: html
<!doctype html>
<html lang="en">
<head><title>Hello</title></head>
<body><h1>Hello, World!</h1></body>
</html>
┌────────────────────────────────── html ──────────────────────────────────┐
│ <!doctype html> │
│ <html lang="en"> │
│ <head><title>Hello</title></head> │
│ <body><h1>Hello, World!</h1></body> │
│ </html> │
└──────────────────────────────────────────────────────────────────────────┘
code-block: Rust
.. code-block:: rust
fn main() {
let greeting = "Hello, World!";
println!("{}", greeting);
}
┌────────────────────────────────── rust ──────────────────────────────────┐
│ fn main() { │
│ let greeting = "Hello, World!"; │
│ println!("{}", greeting); │
│ } │
└──────────────────────────────────────────────────────────────────────────┘
code-block with caption
.. code-block:: python
:caption: example.py
def add(a, b):
# This line is emphasised
return a + b
┌───────────────────────────────── python ─────────────────────────────────┐
│ def add(a, b): │
│ # This line is emphasised │
│ return a + b │
└──────────────────────────────────────────────────────────────────────────┘
productionlist directive
.. productionlist::
statement : expression NEWLINE
expression : term ('+' term)*
term : factor ('*' factor)*
┌───────────────────────────── productionlist ─────────────────────────────┐
│ statement : expression NEWLINE │
│ expression : term ('+' term)* │
│ term : factor ('*' factor)* │
└──────────────────────────────────────────────────────────────────────────┘
Admonitions
note
.. note::
This is a note admonition.
╭───────────────────────────────── Note: ─────────────────────────────────╮
│ This is a note admonition. │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
warning
.. warning::
This is a warning.
╭─────────────────────────────── Warning: ────────────────────────────────╮
│ This is a warning. │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
tip
.. tip::
This is a tip.
╭───────────────────────────────── Tip: ──────────────────────────────────╮
│ This is a tip. │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
important
.. important::
This is important.
╭────────────────────────────── IMPORTANT: ───────────────────────────────╮
│ This is important. │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
hint
.. hint::
This is a hint.
╭───────────────────────────────── Hint: ─────────────────────────────────╮
│ This is a hint. │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
attention
.. attention::
Pay attention to this.
╭────────────────────────────── Attention: ───────────────────────────────╮
│ Pay attention to this. │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
caution
.. caution::
Exercise caution here.
╭─────────────────────────────── Caution: ────────────────────────────────╮
│ Exercise caution here. │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
danger
.. danger::
Danger! Proceed carefully.
╭──────────────────────────────── DANGER: ────────────────────────────────╮
│ Danger! Proceed carefully. │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
error
.. error::
An error occurred.
╭──────────────────────────────── ERROR: ─────────────────────────────────╮
│ An error occurred. │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
Admonition with bold content (box-char rendering test)
.. warning::
**Never** commit secrets to version control.
Use environment variables or a secrets manager instead.
╭─────────────────────────────── Warning: ────────────────────────────────╮
│ Never commit secrets to version control. Use environment variables or a │
│ secrets manager instead. │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
Note with code and emphasis
.. note::
Call ``sys.exit(0)`` to terminate *successfully*,
or ``sys.exit(1)`` for **failure**.
╭───────────────────────────────── Note: ─────────────────────────────────╮
│ Call sys.exit(0) to terminate successfully, or sys.exit(1) for failure. │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
Generic admonition with custom title
.. admonition:: Did you know?
rich-rst supports all currently documented RST elements.
╭───────────────────────────── Did you know? ──────────────────────────────╮
│ rich-rst supports all currently documented RST elements. │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
Admonition with nested content
.. note::
Notes can contain **bold**, *italic*, and ``code``.
They can also contain lists:
- item one
- item two
╭───────────────────────────────── Note: ─────────────────────────────────╮
│ Notes can contain bold, italic, and code. │
│ │
│ They can also contain lists: │
│ │
│ • item one │
│ │
│ • item two │
│ │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
Tables
Simple table with header
===== ===== ======
Col A Col B Col C
===== ===== ======
1 2 3
4 5 6
===== ===== ======
┏━━━━━━━┳━━━━━━━┳━━━━━━━┓
┃ Col A ┃ Col B ┃ Col C ┃
┡━━━━━━━╇━━━━━━━╇━━━━━━━┩
│ 1 │ 2 │ 3 │
├───────┼───────┼───────┤
│ 4 │ 5 │ 6 │
└───────┴───────┴───────┘
Grid table with row spanning
+------------+------------+
| Column 1 | Column 2 |
+============+============+
| Rows 1 & 2 | Row 1 |
+ +------------+
| | Row 2 |
+------------+------------+
┏━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Column 1 ┃ Column 2 ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━┩
│ Rows 1 & 2 │ Row 1 │
│ ├──────────┤
│ │ Row 2 │
└────────────┴──────────┘
Wider grid table
+--------+-------+------+---------+
| Name | Type | Size | Default |
+========+=======+======+=========+
| width | int | 4 | 80 |
+--------+-------+------+---------+
| height | int | 4 | 24 |
+--------+-------+------+---------+
| title | str | var | '' |
+--------+-------+------+---------+
┏━━━━━━━━┳━━━━━━┳━━━━━━┳━━━━━━━━━┓
┃ Name ┃ Type ┃ Size ┃ Default ┃
┡━━━━━━━━╇━━━━━━╇━━━━━━╇━━━━━━━━━┩
│ width │ int │ 4 │ 80 │
├────────┼──────┼──────┼─────────┤
│ height │ int │ 4 │ 24 │
├────────┼──────┼──────┼─────────┤
│ title │ str │ var │ '' │
└────────┴──────┴──────┴─────────┘
list-table directive
.. list-table:: Comparison
:header-rows: 1
:widths: 30 35 35
* - Library
- Language
- Stars
* - rich
- Python
- 50k+
* - rich-rst
- Python
- 1k+
Comparison
┏━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┓
┃ Library ┃ Language ┃ Stars ┃
┡━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━┩
│ rich │ Python │ 50k+ │
├──────────┼──────────┼───────┤
│ rich-rst │ Python │ 1k+ │
└──────────┴──────────┴───────┘
CSV Table
.. csv-table:: Data
:header: "Name", "Value", "Unit"
:widths: 20, 20, 20
"Speed", "299 792 458", "m/s"
"Charge", "1.602e-19", "C"
"Mass", "9.109e-31", "kg"
Data
┏━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━┓
┃ Name ┃ Value ┃ Unit ┃
┡━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━┩
│ Speed │ 299 792 458 │ m/s │
├────────┼─────────────┼──────┤
│ Charge │ 1.602e-19 │ C │
├────────┼─────────────┼──────┤
│ Mass │ 9.109e-31 │ kg │
└────────┴─────────────┴──────┘
Flat Table: Basic with Stub Column
.. flat-table:: Linux Kernel Subsystems
:header-rows: 1
:stub-columns: 1
* - Subsystem
- Maintainer
- Description
* - Networking
- David S. Miller
- TCP/IP stack and network drivers
* - Memory Management
- Andrew Morton
- Virtual memory, paging, and allocators
* - File Systems
- Linus Torvalds
- VFS layer and filesystem drivers
Linux Kernel Subsystems
┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Subsystem ┃ Maintainer ┃ Description ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Networking │ David S. Miller │ TCP/IP stack and network drivers │
├───────────────────┼─────────────────┼────────────────────────────────────┤
│ Memory Management │ Andrew Morton │ Virtual memory, paging, and │
│ │ │ allocators │
├───────────────────┼─────────────────┼────────────────────────────────────┤
│ File Systems │ Linus Torvalds │ VFS layer and filesystem drivers │
└───────────────────┴─────────────────┴────────────────────────────────────┘
Flat Table: Column Span (:cspan:)
.. flat-table:: Quarterly Results
:header-rows: 1
* - Student
- Q1
- Q2
- Q3
* - :cspan:`3` Grand total — all students, all quarters
* - Alice
- 90
- 85
- 92
* - Bob
- 80
- 88
- 76
Quarterly Results
┏━━━━━━━━━┳━━━━┳━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Student ┃ Q1 ┃ Q2 ┃ Q3 ┃
┡━━━━━━━━━┻━━━━┻━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Grand total — all students, all quarters │
├─────────┬────┬────┬────────────────────────────┤
│ Alice │ 90 │ 85 │ 92 │
├─────────┼────┼────┼────────────────────────────┤
│ Bob │ 80 │ 88 │ 76 │
└─────────┴────┴────┴────────────────────────────┘
Flat Table: Row Span (:rspan:)
.. flat-table:: Produce Prices
:header-rows: 1
* - Category
- Item
- Price
* - :rspan:`1` Fruit
- Apple
- $1.00
* - Banana
- $0.50
* - :rspan:`1` Vegetable
- Carrot
- $0.75
* - Broccoli
- $1.25
Produce Prices
┏━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┓
┃ Category ┃ Item ┃ Price ┃
┡━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━┩
│ Fruit │ Apple │ $1.00 │
│ ├──────────┼───────┤
│ │ Banana │ $0.50 │
├───────────┼──────────┼───────┤
│ Vegetable │ Carrot │ $0.75 │
│ ├──────────┼───────┤
│ │ Broccoli │ $1.25 │
└───────────┴──────────┴───────┘
Flat Table: Combined :cspan: and :rspan:
.. flat-table:: Combined Spans
:header-rows: 3
* - Full-width title header
* - :cspan:`1` header 1
- :cspan:`1` header 2
- :cspan:`1` header 3
* - Sub-header 1
- Sub-header 2
- Sub-header 3
- Sub-header 4
- Sub-header 5
- Sub-header 6
* - :rspan:`1` :cspan:`1` Big cell spanning 2 rows and 2 column
- :cspan:`1` Large cell spanning 2 columns
- :cspan:`3` Large cell spanning 4 columns
* - :rspan:`1` Tall cell spanning 2 rows
- Cell 3
- :rspan:`1` :cspan:`2` Big cell spanning 2 rows and 3 columns
* - Cell 1
- Cell 2
- Cell 4
-
Combined Spans
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Full-width title header ┃
┣━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┫
┃ header 1 ┃ header 2 ┃ header 3 ┃
┣━━━━━━━━━━━┳━━━━━━━━━━━╋━━━━━━━━━━━━┳━━━━━━━━━━━━╋━━━━━━━━━━━━┳━━━━━━━━━━━┫
┃ Sub-heade ┃ Sub-heade ┃ Sub-header ┃ Sub-header ┃ Sub-header ┃ Sub-heade ┃
┃ r 1 ┃ r 2 ┃ 3 ┃ 4 ┃ 5 ┃ r 6 ┃
┡━━━━━━━━━━━┻━━━━━━━━━━━╇━━━━━━━━━━━━┻━━━━━━━━━━━━╇━━━━━━━━━━━━┻━━━━━━━━━━━┩
│ Big cell spanning 2 │ Large cell spanning 2 │ Large cell spanning 4 │
│ rows and 2 column │ columns │ columns │
│ ├────────────┬────────────┼────────────────────────┤
│ │ Tall cell │ Cell 3 │ Big cell spanning 2 │
│ │ spanning 2 │ │ rows and 3 columns │
│ │ rows │ │ │
├───────────┬───────────┤ ├────────────┤ │
│ Cell 1 │ Cell 2 │ │ Cell 4 │ │
└───────────┴───────────┴────────────┴────────────┴────────────────────────┘
flat-table — single cell with :cspan: and :rspan: (2×2 block)
.. flat-table:: 2×2 merged cell
:header-rows: 1
* - Task
- Mon
- Tue
- Wed
- Thu
- Fri
* - :cspan:`2` :rspan:`1` Planning
- Review
* - Deploy
* - Others.
2×2 merged cell
┏━━━━━━┳━━━━━┳━━━━━┳━━━━━┳━━━━━┳━━━━━┓
┃ Task ┃ Mon ┃ Tue ┃ Wed ┃ Thu ┃ Fri ┃
┡━━━━━━┻━━━━━┻━━━━━╇━━━━━┻━━━━━┻━━━━━┩
│ Planning │ Review │
│ ├─────────────────┤
│ │ Deploy │
├──────────────────┴─────────────────┤
│ Others. │
└────────────────────────────────────┘
flat-table — :cspan: fills merged column width without inflation
.. flat-table:: Team Overview
:header-rows: 1
* - Name
- Role
* - :cspan:`1` Both columns
* - Alice
- Lead
* - Bob
- Dev
Team Overview
┏━━━━━━━┳━━━━━━┓
┃ Name ┃ Role ┃
┡━━━━━━━┻━━━━━━┩
│ Both columns │
├───────┬──────┤
│ Alice │ Lead │
├───────┼──────┤
│ Bob │ Dev │
└───────┴──────┘
Footnotes and Citations
Manual footnote
See the footnote [1]_ for details.
.. [1] This is the footnote text.
See the footnote [1] for details.
┌───────────────────────────────── Footer ─────────────────────────────────┐
│ 1: This is the footnote text. │
└──────────────────────────────────────────────────────────────────────────┘
Auto-numbered footnote
First reference [#]_.
Second reference [#]_.
.. [#] First auto footnote.
.. [#] Second auto footnote.
First reference [1]. Second reference [2].
┌───────────────────────────────── Footer ─────────────────────────────────┐
│ 1: First auto footnote. │
│ 2: Second auto footnote. │
└──────────────────────────────────────────────────────────────────────────┘
Named auto footnote
See [#note]_ for details.
.. [#note] The named auto footnote.
See [1] for details.
┌───────────────────────────────── Footer ─────────────────────────────────┐
│ 1: The named auto footnote. │
└──────────────────────────────────────────────────────────────────────────┘
Symbol footnote
Marked with a symbol [*]_.
.. [*] Symbol footnote text.
Marked with a symbol [*].
┌───────────────────────────────── Footer ─────────────────────────────────┐
│ *: Symbol footnote text. │
└──────────────────────────────────────────────────────────────────────────┘
Citation
As described in [Doe2023]_.
.. [Doe2023] John Doe. *Python Patterns*. 2023.
As described in Doe2023.
┌──────────────────────────────── citation ────────────────────────────────┐
│ Doe2023: John Doe. Python Patterns. 2023. │
└──────────────────────────────────────────────────────────────────────────┘
Hyperlinks and Targets
Standalone hyperlink
Visit https://python.org for more.
Visit https://python.org for more.
External hyperlink (named)
Read the `Rich documentation`_.
.. _Rich documentation: https://rich.readthedocs.io
Read the Rich documentation.
Internal cross-reference (indirect target)
Jump to `Target Section`_.
Target Section
~~~~~~~~~~~~~~
Content here.
Jump to Target Section.
╭──────────────────────────────────────────────────────────────────────────╮
│ Target Section │
╰──────────────────────────────────────────────────────────────────────────╯
Content here.
Anonymous hyperlink
See `this page <https://example.com>`__ for details.
See this page for details.
Substitutions
Text substitution
|project| is written in Python.
.. |project| replace:: rich-rst
rich-rst is written in Python.
Date substitution
Generated on |today|.
.. |today| date:: %Y-%m-%d
Generated on 2026-05-12.
Unicode substitution
Copyright |copy| 2024 The Authors.
.. |copy| unicode:: U+00A9 .. copyright sign
Copyright © 2024 The Authors.
Image substitution
Click the |logo| icon.
.. |logo| image:: https://example.com/logo.png
:alt: Logo
Click the 🌆 Logo icon.
Images and Figures
image directive
.. image:: https://example.com/photo.png
:alt: A photo
:width: 400px
🌆 A photo
figure directive
.. figure:: https://example.com/chart.png
:alt: A chart
:width: 600px
Figure caption goes here.
╭─ Figure caption goes here. ─╮
│ 🌆 A chart │
╰─────────────────────────────╯
figure with legend
.. figure:: https://example.com/diagram.png
:alt: Diagram
Caption text.
Legend text with more details about the figure.
╭───────────────── Caption text. ─────────────────╮
│ 🌆 Diagram │
│ Legend text with more details about the figure. │
╰─────────────────────────────────────────────────╯
Document Structure Directives
topic directive
.. topic:: Interesting Fact
This is the topic body.
It can contain any body elements.
╭──────────────────────────── Interesting Fact ────────────────────────────╮
│ This is the topic body. It can contain any body elements. │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
rubric directive
.. rubric:: An Unnumbered Heading
Following paragraph.
╭──────────────────────────────────────────────────────────────────────────╮
│ An Unnumbered Heading │
╰──────────────────────────────────────────────────────────────────────────╯
Following paragraph.
contents directive (table of contents)
.. contents:: Table of Contents
:depth: 2
Section A
---------
Content A.
Section B
---------
Content B.
╭─────────────────────────── Table of Contents ────────────────────────────╮
│ • Section A │
│ │
│ • Section B │
│ │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────────────────────╮
│ Section A │
╰──────────────────────────────────────────────────────────────────────────╯
Content A.
╭──────────────────────────────────────────────────────────────────────────╮
│ Section B │
╰──────────────────────────────────────────────────────────────────────────╯
Content B.
sectnum directive
.. sectnum::
Overview
--------
Details
-------
╭──────────────────────────────────────────────────────────────────────────╮
│ 1 Overview │
╰──────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────────────────────╮
│ 2 Details │
╰──────────────────────────────────────────────────────────────────────────╯
header directive
.. header:: My Document Header
Main content.
╔════════════════════════════════ caption ═════════════════════════════════╗
║ My Document Header ║
╚══════════════════════════════════════════════════════════════════════════╝
Main content.
centered directive
.. centered:: IMPORTANT NOTICE
Body text.
IMPORTANT NOTICE
Body text.
Math
Inline math role
The Pythagorean theorem: :math:`a^2 + b^2 = c^2`.
The Pythagorean theorem: a^2 + b^2 = c^2.
math directive (display)
.. math::
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
┌────────────────────────────────── math ──────────────────────────────────┐
│ ∫_-∞^∞ e^-x^2 dx = √(π) │
└──────────────────────────────────────────────────────────────────────────┘
math directive (labeled)
.. math:: E = mc^2
:label: einstein
┌────────────────────────────────── math ──────────────────────────────────┐
│ E = mc^2 │
└──────────────────────────────────────────────────────────────────────────┘
Document Info (docinfo)
Standard docinfo fields
My Report
=========
:Author: Jane Smith
:Date: 2024-01-15
:Version: 1.0
:Status: Draft
:Copyright: 2024 Jane Smith
:Organization: ACME Corp
Body of the document.
╔══════════════════════════════════════════════════════════════════════════╗
║ My Report ║
╚══════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┓
┃ Field Name ┃ Field Value ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━┩
│ Author │ Jane Smith │
├──────────────┼─────────────────┤
│ Date │ 2024-01-15 │
├──────────────┼─────────────────┤
│ Version │ 1.0 │
├──────────────┼─────────────────┤
│ Status │ Draft │
├──────────────┼─────────────────┤
│ Copyright │ 2024 Jane Smith │
├──────────────┼─────────────────┤
│ Organization │ ACME Corp │
└──────────────┴─────────────────┘
Body of the document.
Raw Directive
raw html directive
.. raw:: html
<strong>Bold via raw HTML</strong>
┌─────────────────────────── stripped raw html ────────────────────────────┐
│ Bold via raw HTML │
└──────────────────────────────────────────────────────────────────────────┘
raw latex directive
.. raw:: latex
\textbf{Bold via LaTeX}
┌─────────────────────────────── raw latex ────────────────────────────────┐
│ \textbf{Bold via LaTeX} │
└──────────────────────────────────────────────────────────────────────────┘
Sphinx Version Directives
versionadded
.. versionadded:: 2.1
This feature was added in version 2.1.
╭─────────────────────────── New in version 2.1 ───────────────────────────╮
│ This feature was added in version 2.1. │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
versionchanged
.. versionchanged:: 3.0
The API changed in version 3.0.
╭───────────────────────── Changed in version 3.0 ─────────────────────────╮
│ The API changed in version 3.0. │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
deprecated
.. deprecated:: 1.5
Use the new API instead.
╭────────────────────── Deprecated since version 1.5 ──────────────────────╮
│ Use the new API instead. │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
deprecated-removed
.. deprecated-removed:: 1.5 2.0
Removed in 2.0. Use the new API.
╭───────────── Deprecated since version 1.5 (removed in 2.0) ──────────────╮
│ Removed in 2.0. Use the new API. │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
Sphinx Cross-Reference Roles
:func: role
Call :func:`os.path.join` to join paths.
Call os.path.join to join paths.
:class: role
Use :class:`pathlib.Path` for path handling.
Use pathlib.Path for path handling.
:meth: role
Call :meth:`str.upper` to uppercase a string.
Call str.upper to uppercase a string.
:attr: role
Access :attr:`os.sep` for the path separator.
Access os.sep for the path separator.
:mod: role
The :mod:`os.path` module provides path utilities.
The os.path module provides path utilities.
:exc: role
Raises :exc:`ValueError` when the input is invalid.
Raises ValueError when the input is invalid.
:obj: role
Set :obj:`sys.path` to control module lookup.
Set sys.path to control module lookup.
:data: role
Read :data:`sys.version` for the Python version.
Read sys.version for the Python version.
:const: role
The value of :const:`math.pi` is approximately 3.14.
The value of math.pi is approximately 3.14.
:term: role
A :term:`decorator` wraps another function.
A decorator wraps another function.
:ref: role (cross-reference)
See :ref:`some-label` for details.
See some-label for details.
:doc: role
Refer to :doc:`installation` for setup instructions.
Refer to installation for setup instructions.
:envvar: role
Set :envvar:`PYTHONPATH` before running.
Set PYTHONPATH before running.
Python Domain Directives
py:function
.. py:function:: greet(name: str) -> str
Return a greeting for *name*.
:param name: The name to greet.
:type name: str
:returns: A greeting string.
:rtype: str
╭─────────────────── [function] greet(name: str) -> str ───────────────────╮
│ Return a greeting for name. │
│ │
│ Parameters │
│ name: str │
│ The name to greet. │
│ │
│ Returns │
│ str: A greeting string. │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
py:class
.. py:class:: MyClass(value)
A simple example class.
:param value: Initial value.
:type value: int
╭───────────────────────── [class] MyClass(value) ─────────────────────────╮
│ A simple example class. │
│ │
│ Parameters │
│ value: int │
│ Initial value. │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
py:method
.. py:method:: MyClass.process(data)
Process the given *data*.
╭───────────────────── [method] MyClass.process(data) ─────────────────────╮
│ Process the given data. │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
py:attribute
.. py:attribute:: MyClass.value
:type: int
The current value.
╭─────────────────────── [attribute] MyClass.value ────────────────────────╮
│ Details │
│ ┏━━━━━━━━━━┳━━━━━━━┓ │
│ ┃ Property ┃ Value ┃ │
│ ┡━━━━━━━━━━╇━━━━━━━┩ │
│ │ Type │ int │ │
│ └──────────┴───────┘ │
│ │
│ The current value. │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
py:data
.. py:data:: MAX_RETRIES
:value: 3
Maximum number of retry attempts.
╭─────────────────────────── [data] MAX_RETRIES ───────────────────────────╮
│ Details │
│ Value: 3 │
│ │
│ Maximum number of retry attempts. │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
py:exception
.. py:exception:: MyError
Raised when something goes wrong.
╭────────────────────────── [exception] MyError ───────────────────────────╮
│ Raised when something goes wrong. │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
py:module
.. py:module:: mypackage.core
Core functionality for mypackage.
╭──────────────────────── [module] mypackage.core ─────────────────────────╮
│ Core functionality for mypackage. │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
py:decorator
.. py:decorator:: cached(func)
Cache the return value of *func*.
╭──────────────────────── [decorator] cached(func) ────────────────────────╮
│ Cache the return value of func. │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
See Also
seealso directive
.. seealso::
:func:`os.path.join`, :class:`pathlib.Path`
╭──────────────────────────────── See Also ────────────────────────────────╮
│ os.path.join, pathlib.Path │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
Toctree (Sphinx)
toctree directive
.. toctree::
:maxdepth: 2
:caption: Contents
installation
usage
api
╭──────────────────────────────── Contents ────────────────────────────────╮
│ • installation │
│ • usage │
│ • api │
╰──────────────────────────────────────────────────────────────────────────╯
toctree with numbered entries
.. toctree::
:numbered:
intro
guide/installation
guide/usage
guide/api
╭──────────────────────────────── Contents ────────────────────────────────╮
│ 1. intro │
│ 1.1. guide/installation │
│ 1.2. guide/usage │
│ 1.3. guide/api │
╰──────────────────────────────────────────────────────────────────────────╯
Glossary
glossary directive
.. glossary::
RST
reStructuredText — a lightweight markup language.
Sphinx
A documentation generator for Python projects.
╭──────────────────────────────── Glossary ────────────────────────────────╮
│ RST │
│ reStructuredText — a lightweight markup language. │
│ │
│ Sphinx │
│ A documentation generator for Python projects. │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
glossary (sorted)
.. glossary::
:sorted:
Zebra
A striped animal.
Aardvark
An ant-eating mammal.
╭──────────────────────────────── Glossary ────────────────────────────────╮
│ Aardvark │
│ An ant-eating mammal. │
│ │
│ Zebra │
│ A striped animal. │
│ │
╰──────────────────────────────────────────────────────────────────────────╯
Mixed Sphinx Roles in Prose
Mixed roles in a paragraph
Use :func:`json.dumps` or :func:`json.loads` to serialize data.
The :class:`dict` type maps :class:`str` keys to values.
See :pep:`484` for type hints and :pep:`526` for variable annotations.
Press :kbd:`Ctrl+D` or call :func:`exit` to quit the REPL.
Use json.dumps or json.loads to serialize data. The dict type maps str keys
to values. See PEP 484 for type hints and PEP 526 for variable annotations.
Press Ctrl+D or call exit to quit the REPL.
This page was generated automatically. Run python tools/generate_demo_page.py
from the repository root to refresh it.
Comments
RST comment (invisible)
Before comment. .. This is an RST comment and should not appear in output. After comment.Before comment. After comment.