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 |.

Only nested code blocks (and literalinclude) are merged. Other nested content is skipped, and Sphinx emits a warning for each skipped node. Use -W to treat those warnings as errors.

MyST Markdown

With MyST Parser, nest directives using a longer outer fence so inner fenced blocks are not truncated:

````{combined-code-block} python
```{code-block} python
x = 1
```

```{code-block} python
y = 2
```
````

Contributing

See CONTRIBUTING.rst.