[Mlir-commits] [mlir] aa4bd22 - [mlir][pygments] add mkdocs instructions and `_all_` addition (#181978)

[llvmlistbot at llvm.org]

Author: Perry Gibson
Date: 2026-03-12T17:02:15Z
New Revision: aa4bd225c267cb947d483a907387f53eb5832628

URL: https://github.com/llvm/llvm-project/commit/aa4bd225c267cb947d483a907387f53eb5832628
DIFF: https://github.com/llvm/llvm-project/commit/aa4bd225c267cb947d483a907387f53eb5832628.diff

LOG: [mlir][pygments] add mkdocs instructions and `_all_` addition (#181978)

Pygments requires __all__ to be defined in lexer modules that are
discovered via the LEXERS entry-point mapping. Without it, importing
the lexer through Pygments' standard plugin machinery fails silently.

This also adds brief usage instructions for integrating the lexer
into documentation pipelines.

Added: 
    

Modified: 
    mlir/utils/pygments/README.md
    mlir/utils/pygments/mlir_lexer.py

Removed: 
    


################################################################################
diff  --git a/mlir/utils/pygments/README.md b/mlir/utils/pygments/README.md
index 838faceb01b0f..09c99b78d8880 100644
--- a/mlir/utils/pygments/README.md
+++ b/mlir/utils/pygments/README.md
@@ -20,6 +20,42 @@ This will produce highlighted output in the terminal. Other output formats are
 available, see Pygments [documentation](https://pygments.org/docs/) for more
 information.
 
+### MkDocs / Python-Markdown
+
+Create a Markdown extension that registers the lexer via Pygments' LEXERS
+mapping:
+
+```python
+# e.g., docs/pygments/mlir.py
+from markdown import Extension
+import pygments.lexers._mapping as _mapping
+
+def _register_mlir_lexer():
+    if "MlirLexer" not in _mapping.LEXERS:
+        _mapping.LEXERS["MlirLexer"] = (
+            "your.module.path.mlir_lexer",  # adjust to your project
+            "MLIR",
+            ("mlir",),
+            ("*.mlir",),
+            ("text/x-mlir",),
+        )
+
+class MlirHighlightExtension(Extension):
+    def extendMarkdown(self, md):
+        _register_mlir_lexer()
+
+def makeExtension(**kwargs):
+    return MlirHighlightExtension(**kwargs)
+```
+
+Add to `mkdocs.yml` (before `pymdownx.highlight`):
+
+```yaml
+markdown_extensions:
+  - your.module.path.mlir
+  - pymdownx.highlight
+```
+
 ### LaTeX Usage
 
 First, make sure your distribution includes the `minted` package and list in
@@ -31,7 +67,7 @@ the preamble.
 
 Place the `mlir_lexer.py` in a place where the `latex` binary can find it,
 typically in the working directory next to the main `.tex` file. Note that you
-will have to invoke `latex` with the `-shell-escape` flag. See the `minted` 
+will have to invoke `latex` with the `-shell-escape` flag. See the `minted`
 package [documentation](https://ctan.org/pkg/minted?lang=en) for more
 information.
 

diff  --git a/mlir/utils/pygments/mlir_lexer.py b/mlir/utils/pygments/mlir_lexer.py
index 4cbe0fe236fc4..2c81e207d906b 100644
--- a/mlir/utils/pygments/mlir_lexer.py
+++ b/mlir/utils/pygments/mlir_lexer.py
@@ -6,6 +6,8 @@
 from pygments.token import *
 import re
 
+__all__ = ["MlirLexer"]
+
 
 class MlirLexer(RegexLexer):
     """Pygments lexer for MLIR.