sphinxcontrib-generate-include

Sphinx extension to allow calling Python functions and including their output as Markdown, ReStructuredText or literal in the Sphinx document.

generate-include directive

This directive executes a Python function from a file and includes its output in the documentation, parsed as Markdown, reStructuredText, or literal text.

   ```{generate-include} path/to/file.py:function_name
   ```

.. generate-include:: path/to/file.py:function_name

Options

  • type: md | rst | literal (default: md)

    • md: Parse output as Markdown using MyST parser

    • rst: Parse output as reStructuredText

    • literal: Include output as preformatted literal block

Example

Assuming the following estimation.py file:

 1from sphinxcontrib.generate_include import mdlib
 2
 3
 4def data_table():
 5    return mdlib.table(
 6        ["Name", "Age", "City"],
 7        [
 8            ["Alice", "30", "New York"],
 9            ["Bob", "25", "Los Angeles"],
10            ["Charlie", "35", "Chicago"],
11        ],
12        alignment=["l", "r", "c"],
13    )

As mentioned above it can be included like this:

   ```{generate-include} estimation.py:data_table
   ```

.. generate-include:: estimation.py:data_table

And it will then create a table like this:

Name

Age

City

Alice

30

New York

Bob

25

Los Angeles

Charlie

35

Chicago