sphinx:デフォルトのコードブロックの言語は`default`で`python3`に近いもの

実行環境

• Python 3.9.7
• sphinx 4.4.0

はじめに

sphinxでHTMLドキュメントを生成しています。

以下のような設定ファイルを使って、HTMLドキュメントを生成してみます。

conf.py

project = "foo-bar"

index.rst

==================================================
test
==================================================

.. code-block::

   $ foo-bar list


.. code-block::

   usage: foo-bar list [-h] [--debug] [-o OUTPUT]


.. code-block::

   def foo(a: int, b: int) -> int:
      return a + b

$ ls
conf.py  index.rst

$ sphinx-build -b html  . _build 

$ ls
_build  conf.py  index.rst

HTMLドキュメントが生成されました。
2つ目のコードブロックでは、listと-がハイライトされています。2つ目のコードブロックはコマンドのヘルプなので、このハイライトは期待したものではありません。なぜハイライトされるのでしょうか？

ハイライトされる原因

code-blockディレクティブの言語が指定されていなければ、highlightディレクティブの言語、またはhighlight_languageの設定が使われます。

This directive takes a language name as an argument. It can be any lexer alias supported by Pygments. If it is not given, the setting of highlight directive will be used. If not set, highlight_language will be used.

そしてhighlight_languageのデフォルト値はdefaultで、これはpython3に近いものです。

The default language to highlight source code in. The default is 'default'. It is similar to 'python3'; it is mostly a superset of 'python' but it fallbacks to 'none' without warning if failed. 'python3' and other languages will emit warning if failed.

したがって、2つ目のコードブロックはpythonとみなされて、listと-がハイライトされるようです。

解決策

code-blockディレクティブの言語をtextまたはnoneにすれば、ハイライトされなくなります。¹

index.rst

.. code-block:: text

   usage: foo-bar list [-h] [--debug] [-o OUTPUT]

ドキュメントで利用するコードブロックの言語が、ほとんどpythonでないのであれば、conf.pyのhighlight_languageを変えるのがよいでしょう。

conf.py

project = "foo-bar"
highlight_language = "text"

1. textとnoneは両方ともPygmentsのTextLexerを指しています。https://ja.stackoverflow.com/questions/85909 ↩