sphinx-inlinecode

sphinx-inlinecode is a Sphinx extension that embeds source code blocks directly into your documentation as a dropdown.

Example

sphinx_inlinecode.get_code_block(qualname, obj, highlighter)View on GitHub

View Source Code

def get_code_block(qualname: str, obj: Any, highlighter: PythonLexer) -> BeautifulSoup:
    """Parses and highlights the source code lines of the provided object

    :param qualname: the fully qualified name of the object
    :param obj: the actual object to retrieve the source code lines from
    :param highlighter: the Pygments lexer to highlight the code block with
    :return: the highlighted and fully formatted HTML codeblock to insert
    """
    sourcelines, _ = inspect.getsourcelines(obj)
    initial_indent = len(sourcelines[0]) - len(sourcelines[0].lstrip())

    if initial_indent:  # Remove common leading whitespace
        pattern = fr"[ ]{{{initial_indent}}}(.*)"
        sourcelines = (
            re.sub(pattern, r"\1", line)
            for line in sourcelines
        )
    # Convert to HTML code block with syntax highlighting
    highlighted = highlighter.highlight_block(
        source=''.join(sourcelines),
        lang='python',
        linenos=False
    )
    lines = highlighted.splitlines()
    before, after = re.split(r"<pre>(?:<span></span>)?", lines[0])
    lines[0] = f'{before}<pre><div class="viewcode-block" id="{qualname}">{after}'

    code_block = '\n'.join(lines)
    return wrap_code_block(code_block)

Parses and highlights the source code lines of the provided object

Parameters:

• qualname (str) – the fully qualified name of the object

• obj (Any) – the actual object to retrieve the source code lines from

• highlighter (PythonLexer) – the Pygments lexer to highlight the code block with

Returns:

the highlighted and fully formatted HTML codeblock to insert

Return type:

BeautifulSoup

Unlike sphinx.ext.viewcode, source code blocks will also be added for property and cached_property entries

Installation

To install sphinx-inlinecode via pip:

pip install sphinx-inlinecode

Configuration

Add the extension to your conf.py

extensions = [
    "sphinx_inlinecode",
]