[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.

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.
 

mlir/utils/pygments/mlir_lexer.py

@@ -6,6 +6,8 @@ from pygments.lexer import RegexLexer, bygroups, include, using
 from pygments.token import *
 import re
 
+__all__ = ["MlirLexer"]
+
 
 class MlirLexer(RegexLexer):
     """Pygments lexer for MLIR.