Embedding Literals
Directive: literal-block – embed blocks of text
Added value includes facilities for rendering mutliline strings as blocks of text, with optional syntax highlighting.
The directive accepts two arguments:
.. literal-block:: module.data
:language: yaml
Other options include the :linenos:
flag to show line numbers:
.. literal-block:: module.data
:language: json
:linenos:
and highlighting of optional lines using :highlight-lines:
:
.. literal-block:: module.data
:language: toml
:emphasize-lines: 8, 10, 16
Basic Examples
JSON literal
Consider the following Python data structure representing some facts about a few Nordic countries, and the code to render it into a string as a JSON literal:
import json
countries = [
dict(
name="Denmark",
code="DK",
area_km2=42933,
population_millions=5.85,
currency="DKK",
),
dict(
name="Norway",
code="NO",
area_km2=385207,
population_millions=5.39,
currency="NOK",
),
dict(
name="Sweden",
code="SE",
area_km2=450295,
population_millions=10.40,
currency="SEK",
)
]
json_countries = json.dumps(countries, indent=2)
This is how we would refer to that this JSON literal using a literal-block::
directive:
.. literal-block:: countries.json_countries
:language: json
which will be rendered like this:
[
{
"name": "Denmark",
"code": "DK",
"area_km2": 42933,
"population_millions": 5.85,
"currency": "DKK"
},
{
"name": "Norway",
"code": "NO",
"area_km2": 385207,
"population_millions": 5.39,
"currency": "NOK"
},
{
"name": "Sweden",
"code": "SE",
"area_km2": 450295,
"population_millions": 10.4,
"currency": "SEK"
}
]