Support more Python Pygments lexer aliases (felix-hilden#162)

cmarqu · web-flow · commit 92ee4541bdda · 2025-02-11T04:58:50.000+02:00
Closes felix-hilden#160
diff --git a/docs/src/examples.rst b/docs/src/examples.rst
@@ -23,8 +23,13 @@ Different import styles are supported, along with all Python syntax.
 Star imports might be particularly handy in code examples.
 `Doctest <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
 #doctest-blocks>`_ and console blocks using :code:`.. code:: pycon` work too.
-Including code via :rst:dir:`literalinclude` requires using a
-:code:`:language: py` parameter.
+Including code via :rst:dir:`literalinclude` requires using one of the following parameters:
+:code:`:language: python`, :code:`:language: python3`,
+:code:`:language: py`, :code:`:language: py3`, :code:`:language: pyi`,
+:code:`:language: sage`, :code:`:language: bazel`, :code:`:language: starlark`
+(i.e., the list of
+`Pygments Lexers <https://pygments.org/docs/lexers/#pygments.lexers.python.PythonLexer>`_).
+
 
 .. code:: pycon
 
diff --git a/docs/src/release_notes.rst b/docs/src/release_notes.rst
@@ -8,6 +8,10 @@ These release notes are based on
 sphinx-codeautolink adheres to
 `Semantic Versioning <https://semver.org>`_.
 
+0.16.3 (unreleased)
+-------------------
+- Add more Pygments lexer aliases in code blocks (:issue:`160`)
+
 0.16.2 (2025-01-16)
 -------------------
 - Fix regression in not handling malformed return types (:issue:`159`)
diff --git a/src/sphinx_codeautolink/extension/block.py b/src/sphinx_codeautolink/extension/block.py
@@ -17,7 +17,17 @@
 from .backref import CodeExample
 from .directive import ConcatMarker, PrefaceMarker, SkipMarker
 
-BUILTIN_BLOCKS = {"python": None, "py": None}
+# list from https://pygments.org/docs/lexers/#pygments.lexers.python.PythonLexer
+BUILTIN_BLOCKS = {
+    "python": None,
+    "python3": None,
+    "py": None,
+    "py3": None,
+    "pyi": None,
+    "sage": None,
+    "bazel": None,
+    "starlark": None,
+}
 
 
 @dataclass
diff --git a/tests/extension/ref/pygments_lexer_code-block_bazel.txt b/tests/extension/ref/pygments_lexer_code-block_bazel.txt
@@ -0,0 +1,13 @@
+test_project
+test_project.bar
+# split
+# split
+Test project
+============
+
+.. code-block:: bazel
+
+   import test_project
+   test_project.bar()
+
+.. automodule:: test_project
diff --git a/tests/extension/ref/pygments_lexer_code-block_py3.txt b/tests/extension/ref/pygments_lexer_code-block_py3.txt
@@ -0,0 +1,13 @@
+test_project
+test_project.bar
+# split
+# split
+Test project
+============
+
+.. code-block:: py3
+
+   import test_project
+   test_project.bar()
+
+.. automodule:: test_project
diff --git a/tests/extension/ref/pygments_lexer_code-block_pyi.txt b/tests/extension/ref/pygments_lexer_code-block_pyi.txt
@@ -0,0 +1,13 @@
+test_project
+test_project.bar
+# split
+# split
+Test project
+============
+
+.. code-block:: pyi
+
+   import test_project
+   test_project.bar()
+
+.. automodule:: test_project
diff --git a/tests/extension/ref/pygments_lexer_code-block_python3.txt b/tests/extension/ref/pygments_lexer_code-block_python3.txt
@@ -0,0 +1,13 @@
+test_project
+test_project.bar
+# split
+# split
+Test project
+============
+
+.. code-block:: python3
+
+   import test_project
+   test_project.bar()
+
+.. automodule:: test_project
diff --git a/tests/extension/ref/pygments_lexer_code-block_sage.txt b/tests/extension/ref/pygments_lexer_code-block_sage.txt
@@ -0,0 +1,13 @@
+test_project
+test_project.bar
+# split
+# split
+Test project
+============
+
+.. code-block:: sage
+
+   import test_project
+   test_project.bar()
+
+.. automodule:: test_project
diff --git a/tests/extension/ref/pygments_lexer_code-block_starlark.txt b/tests/extension/ref/pygments_lexer_code-block_starlark.txt
@@ -0,0 +1,13 @@
+test_project
+test_project.bar
+# split
+# split
+Test project
+============
+
+.. code-block:: starlark
+
+   import test_project
+   test_project.bar()
+
+.. automodule:: test_project
