📝 Enable Interactive MLIR Documentation via Python Bindings & MyST

[DRovara]

Problem Statement

Currently, our documentation for the MQT MLIR dialects relies on static code blocks. To improve user adoption and clarity, we want to mirror the "notebook" experience found in other parts of this repository's docs (like here).

To this end, we want to enable executable MyST notebooks (e.g. here) for our MLIR dialects. This would allow users to view the documentation with execution results from MLIR code blocks (i.e. performing some MLIR parsing and optimization), seeing the results directly in the browser.

Since the documentation build process utilizes Python (Sphinx + MyST-NB), we need a way to invoke our MLIR parser and optimizer passes directly from Python.

Proposed Solution

The implementation should follow the established MQT docs workflow.
This requires exposing our C++ MLIR infrastructure to Python.

The work should be divided into the following phases:

A. Build Infrastructure (Enable MLIR)
Update the Python build system/python bindings to enable MLIR functions for parsing and optimization in the Python wheels.

B. Investigation & Bindings Strategy
We need to determine the best way to expose the MLIR functionality to Python.
Investigate Upstream: Evaluate how much of the MLIR Python bindings we can leverage vs. what needs to be custom.
Reference Architecture: Analyze Catalyst (and similar projects) to see how they handle MLIR-to-Python bindings for inspiration.

C. Documentation & Notebooks
Update one of the MLIR documentation guides in this repository.
Replace one of the MLIR code blocks in there with a MyST code block using the exposed python binding.
Alternatively, add a new MLIR code example in there to show off the main functionalities of these new MyST code blocks.