Pass code type to Sphinx `.. include::` directive

Question

I want to include full example scripts in Sphinx documentation. I originally simply duplicated an example file using a .. code:: directive, dropping in the entire python and json files for the example.

I then found the .. include:: directive, which lets to link to files by providing their relative path, and by using the code option, "The argument and the included content are passed to the code directive". This works fine for my python files, because the default decoding and highlighting for the code directive is python. But my json files are not highlighted as json. How do I indicate what code format the code directive should use to parse the code?

This is what I am using.

.. include:: ../../examples/my_example.json
    :code:

I tried adding changing the second line to :code: json with no effect.

This is what I had originally, but want to replace so the example code does not have to be maintained in both the documentation and the examples.

.. code-block:: json
    :name: my_example.json
    :caption: my_example.json

    {
        "field1": "attribute1",
        "field2": "attribute2",
        "field3": true,
        ...
    }

It seems like literalinclude is what you want: stackoverflow.com/q/18801693/407651 — mzjn

Steven C. Howell Steven C. Howell · Accepted Answer · 2021-08-27T19:38:34

The solution is to instead use the literalinclude directive which has a language option. This is how it should look.

.. literalinclude:: ../../examples/my_example.json
    :language: json

Note that literal include also supports options like linenos, lines, start-after, and end-before, caption, and name.

Pass code type to Sphinx `.. include::` directive

1 Answers