code-blocks.rst

Code Blocks

https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#showing-code-examples

Literal Blocks

https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#literal-blocks

https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#literal-blocks

This is a code sample:

print('Hello, world!')

Quoted Literal Blocks

https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#quoted-literal-blocks

Supported initial characters: ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~:

! every line
! must
! start with the same character

code-block Directive

https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block

print('Hello,')
print('wooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooorld!')

# another code block

No language:

┌─┬┐  ╔═╦╗  ╓─╥╖  ╒═╤╕
│ ││  ║ ║║  ║ ║║  │ ││
├─┼┤  ╠═╬╣  ╟─╫╢  ╞═╪╡
└─┴┘  ╚═╩╝  ╙─╨╜  ╘═╧╛
┌───────────────────┐
│  ╔═══╗ Some Text  │▒
│  ╚═╦═╝ in the box │▒
╞═╤══╩══╤═══════════╡▒
│ ├──┬──┤           │▒
│ └──┴──┘           │▒
└───────────────────┘▒
 ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒

:linenos: option:

print('Hello,')
print('wooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooorld!')

# another code block

:linenos: with :lineno-start::

print('Hello,')
print('world!')

:emphasize-lines:

def some_function():
    interesting = False
    print('This line is highlighted.')
    print('This one is not...')
    print('...but this one is.')

:emphasize-lines: and :linenos::

def some_function():
    interesting = False
    print('This line is highlighted.')
    print('This one is not...')
    print('...but this one is.')

:caption::

print('Hello, world!')

:caption: and :linenos::

print('Hello,')
print('world!')

See also [source] link in insipid_sphinx_theme.

parsed-literal Directive

https://docutils.sourceforge.io/docs/ref/rst/directives.html#parsed-literal

Code block with inline markup, e.g. literal text¹.

Code block with nothing special

Warning

Syntax highlighting (including providing a background color) is sometimes broken, see sphinx-doc/sphinx#2167.

Doctest Blocks

https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#doctest-blocks

>>> print('this is a Doctest block') this is a Doctest block

Nesting

Note

'code in note'

Some text with inline code.

'some more code'

Warning

def some_function():
    interesting = False
    print('This line is highlighted.')
    print('This one is not...')
    print('...but this one is.')

Topic

def some_function():
    interesting = False
    print('This line is highlighted.')
    print('This one is not...')
    print('...but this one is.')

Warning

definition term

'code in definition in admonition'

Sidebar

def some_function():
    interesting = False
    print('This line is highlighted.')
    print('This one is not...')
    print('...but this one is.')

Code After Sidebar
==================

.

.

.

.

.

.

.

A long long long long long long long long long long long long long line.

---

1. Having literal text within more literal text probably doesn't make a lot of sense.↩