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"
  }
]