Fix render issue of markdown for python bindings sphinx docs (#239)

Sphinx renders docstrings as reStructuredText, but in our MLIR Python
bindings, many op documentations are generated from TableGen and written
in Markdown. As a result, elements like code blocks are broken in the
rendered output, making the docs hard to read.

In this PR, we hook into Sphinx AutoAPI’s docstring processing function
(since Sphinx AutoAPI doesn’t provide an official way to override it)
and use a CommonMark parser to parse the docstrings and re-emit them as
reStructuredText. This allows Sphinx to render the documentation
correctly.


### Before: 

https://mlir.llvm.org/python-bindings/autoapi/mlir/dialects/_affine_ops_gen/index.html#mlir.dialects._affine_ops_gen.AffineApplyOp
<img width="1576" height="1094" alt="image"
src="https://github.com/user-attachments/assets/bbfc299b-9efb-46b6-863e-ac21903e0ed6"
/>

### After: 

https://mlir-python.surge.sh/autoapi/mlir/dialects/_affine_ops_gen/index.html#mlir.dialects._affine_ops_gen.AffineApplyOp
<img width="1545" height="1199" alt="image"
src="https://github.com/user-attachments/assets/224f5d9b-0677-4169-a32a-eea2edf2fb23"
/>


### Demo
You can preview the website after this change at:
https://mlir-python.surge.sh/

cc @jpienaar @makslevental

Author: PragmaTwice

sphinx-mlir-python/conf.py

@@ -36,7 +36,22 @@
 autoapi_dirs = list(mlir.__path__)
 autoapi_python_use_implicit_namespaces = True
 
+import autoapi._parser as _autoapi_parser
+import commonmark
 
+
+# hook the _prepare_docstring function in sphinx-autoapi,
+# so that we can convert markdown to rst.
+_prepare_docstring = _autoapi_parser._prepare_docstring
+def prepare_docstring(doc):
+    md = _prepare_docstring(doc)
+    ast = commonmark.Parser().parse(md)
+    rst = commonmark.ReStructuredTextRenderer().render(ast)
+    return rst
+_autoapi_parser._prepare_docstring = prepare_docstring
+
+
+# generate an index page for the mlir namespace
 def ensure_mlir_index(_):
     mlir_dir = os.path.join(os.path.dirname(__file__), "autoapi/mlir")
     os.makedirs(mlir_dir, exist_ok=True)

sphinx-mlir-python/requirements.txt

@@ -1,3 +1,4 @@
-sphinx
-sphinx-autoapi
-furo
+Sphinx==8.1.3
+sphinx-autoapi==3.6.1
+furo==2025.9.25
+commonmark==0.9.1