Support default lexer, literal blocks, highlight directive and highlight_language config (#166)

Author: felix-hilden

docs/src/about.rst

@@ -18,7 +18,7 @@ Caveats
 -------
 - **Only works with HTML documentation**, disabled otherwise. If the extension
   is off, it silently removes directives that would produce output.
-- **Only processes literal blocks, not inline code**. Sphinx has great tools
+- **Only processes blocks, not inline code**. Sphinx has great tools
   for linking definitions inline, and longer code should be in a block anyway.
 - **Doesn't run example code**. Therefore all possible resolvable types are not
   found, and the runtime correctness of code cannot be validated.

docs/src/examples.rst

@@ -23,13 +23,8 @@ 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 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>`_).
-
+Including code via :rst:dir:`literalinclude` requires using one of the
+`Python Lexers <https://pygments.org/docs/lexers/#pygments.lexers.python.PythonLexer>`_.
 
 .. code:: pycon
 

docs/src/index.rst

@@ -70,7 +70,7 @@ Caveats
 For a more thorough explanation, see :ref:`about`.
 
 - Only works with HTML documentation
-- Only processes literal blocks, not inline code
+- Only processes blocks, not inline code
 - Doesn't run example code
 - Parsing and type hint resolving is incomplete
 

docs/src/reference.rst

@@ -96,7 +96,7 @@ Directives
 
 .. rst:directive:: .. autolink-concat:: [mode]
 
-   Toggle literal block concatenation.
+   Toggle block concatenation.
    Concatenated code blocks are treated as a continuous source,
    so that imports and statements in previous blocks affect later blocks.
    Concatenation is begun at the directive, not applied retroactively.

docs/src/release_notes.rst

@@ -15,6 +15,8 @@ sphinx-codeautolink adheres to
   a corresponding tutorial or how-to (:issue:`161`)
 - Add more Pygments lexer aliases in code blocks (:issue:`160`)
 - Fix undocumented class attribute leading to a crash (:issue:`165`)
+- Support the ``default`` lexer, literal blocks, ``.. highlight::`` directive
+  and ``highlight_language`` configuration (:issue:`166`)
 
 0.16.2 (2025-01-16)
 -------------------

src/sphinx_codeautolink/extension/__init__.py

@@ -75,6 +75,7 @@ def __init__(self) -> None:
         self.warn_missing_inventory = None
         self.warn_failed_resolve = None
         self.warn_no_backreference = None
+        self.highlight_lang = None
 
         # Populated once
         self.outdated_docs: set[str] = set()
@@ -105,6 +106,7 @@ def build_inited(self, app) -> None:
         self.warn_missing_inventory = app.config.codeautolink_warn_on_missing_inventory
         self.warn_failed_resolve = app.config.codeautolink_warn_on_failed_resolve
         self.warn_no_backreference = app.config.codeautolink_warn_on_no_backreference
+        self.highlight_lang = app.config.highlight_language
 
         # Append static resources path so references in setup() are valid
         app.config.html_static_path.append(
@@ -138,6 +140,7 @@ def parse_blocks(self, app, doctree) -> None:
             global_preface=self.global_preface,
             custom_blocks=self.custom_blocks,
             concat_default=self.concat_default,
+            default_highlight_lang=self.highlight_lang,
         )
         doctree.walkabout(visitor)
         self.cache.transforms[visitor.current_document] = visitor.source_transforms

src/sphinx_codeautolink/extension/block.py

@@ -19,6 +19,7 @@
 
 # list from https://pygments.org/docs/lexers/#pygments.lexers.python.PythonLexer
 BUILTIN_BLOCKS = {
+    "default": None,
     "python": None,
     "python3": None,
     "py": None,
@@ -104,7 +105,7 @@ def clean_ipython(source: str) -> tuple[str, str]:
 
 
 class CodeBlockAnalyser(nodes.SparseNodeVisitor):
-    """Transform literal blocks of Python with links to reference documentation."""
+    """Transform blocks of Python with links to reference documentation."""
 
     def __init__(
         self,
@@ -113,6 +114,7 @@ def __init__(
         global_preface: list[str],
         custom_blocks: dict[str, Callable[[str], str]],
         concat_default: bool,
+        default_highlight_lang: str | None,
         **kwargs,
     ) -> None:
         super().__init__(*args, **kwargs)
@@ -130,6 +132,7 @@ def __init__(
         self.concat_section = False
         self.concat_sources = []
         self.skip = None
+        self.highlight_lang = default_highlight_lang
 
     def unknown_visit(self, node) -> None:
         """Handle and delete custom directives, ignore others."""
@@ -162,6 +165,10 @@ def unknown_visit(self, node) -> None:
     def unknown_departure(self, node) -> None:
         """Ignore unknown nodes."""
 
+    def visit_highlightlang(self, node) -> None:
+        """Set expected highlight language."""
+        self.highlight_lang = node["lang"]
+
     def visit_title(self, node) -> None:
         """Track section names and break concatenation and skipping."""
         self.title_stack.append(node.astext())
@@ -185,7 +192,7 @@ def visit_doctest_block(self, node):
 
     def visit_literal_block(self, node: nodes.literal_block):
         """Visit a generic literal block."""
-        return self.parse_source(node, node.get("language", None))
+        return self.parse_source(node, node.get("language", self.highlight_lang))
 
     def parse_source(
         self, node: nodes.literal_block | nodes.doctest_block, language: str | None

src/sphinx_codeautolink/extension/directive.py

@@ -62,7 +62,7 @@ def copy(self):
 
 
 class Concat(Directive):
-    """Toggle and cut literal block concatenation in a document."""
+    """Toggle and cut block concatenation in a document."""
 
     has_content = False
     required_arguments = 0

tests/extension/ref/pygments_lexer_code-block_bazel.txt renamed to tests/extension/ref/lexer_bazel.txt

@@ -0,0 +1,14 @@
+test_project
+test_project.bar
+# split
+# split
+Test project
+============
+
+.. code::
+
+   import test_project
+
+   test_project.bar()
+
+.. automodule:: test_project