sphinx-combine 2025.11.15

Extension for Sphinx which enables combining code blocks.

Sphinx Combine

Extension for Sphinx which enables combining code blocks.

Contents

• Sphinx Combine

  • Installation

  • Setup

  • Using combined-code-block

  • Contributing

Installation

sphinx-combine is compatible with Sphinx 7.2.0+ using Python 3.11+.

$ pip install sphinx-combine

Setup

Add the following to conf.py to enable the extension:

"""Configuration for Sphinx."""

extensions = ["sphinxcontrib.spelling"]  # Example existing extensions

extensions += ["sphinx_combine"]

Using combined-code-block

The extension provides a new directive, combined-code-block, which allows you to combine multiple code blocks into a single code block.

The directive takes a language argument which is used to determine the syntax, as well as all options that the code-block directive supports.

Languages and options of code blocks within the directive are ignored.

.. combined-code-block:: python

   .. literalinclude:: my_code.js
      :language: javascript

   .. code-block:: python

      """First code block."""

   .. code-block:: cpp

      // Second code block.

By default, there are no blank lines between the code blocks. To add a blank line, use |.

Contributing

See CONTRIBUTING.rst.