Selectively disable readthedocs syntax highlighting

Question

I have an RST file for which I do not want any syntax highlighting. It contains multiple literal blocks and a highlight directive at the top of the file to try to disable syntax highlights:

.. highlight:: none

::

  Text that happens to contain words like list, None, etc.

::

  Another literal block with words like list, None, etc.

Some other RST files in the project use syntax highlighting with directives like this:

.. highlight:: bash

When I build the docs with sphinx on my workstation, sphinx correctly highlights syntax where enabled and disables syntax highlights where it is disabled. However, when built on readthedocs website there is unwanted Python syntax highlighting within the literal blocks in the RST file containing .. highlight:: none. Words like "None" and "list" are highlighted.

How can I selectively disable syntax highlighting in this RST file while keeping the syntax highlights elsewhere?

Answer 1

You use two highlighting directives in direct succession, .. highlight:: none followed immediately by ::. The former gets overridden by the latter which applies the latter language's syntax highlighting.

:: uses the default language configured for syntax highlighting, usually Python3.

I would not use two directives in succession.

I would use only one directive, followed by the code I want to highlight.

As far as which syntax to use, you can use text which is just plain old text, none, or make up something that is not one of the Pygments lexers, like moosehair. See Showing code examples for more information.

.. code-block:: text

    Plain old text

Or if you set in your conf.py, highlight_language = 'none', you can use :::

::

    Plain old text