📝 Optimize MLIR documentation setup (#1216)

## Description

This PR optimizes the MLIR documentation setup:
- adds a dedicated and newly-created `mlir-pygments` package to provide
syntax highlighting for MLIR code blocks
- fixes a link in the MLIR docs
- moves the cleanup logic from the RtD setup to the CMake setup so that
it can be replicated locally
- optimizes the page display for the MLIR docs pages.

## Checklist:

<!---
This checklist serves as a reminder of a couple of things that ensure
your pull request will be merged swiftly.
-->

- [x] The pull request only contains commits that are focused and
relevant to this change.
- [x] I have added appropriate tests that cover the new/changed
functionality.
- [x] I have updated the documentation to reflect these changes.
- [x] I have added entries to the changelog for any noteworthy
additions, changes, fixes, or removals.
- [x] I have added migration instructions to the upgrade guide (if
needed).
- [x] The changes follow the project's style guidelines and introduce no
new warnings.
- [x] The changes are fully tested and pass the CI checks.
- [x] I have reviewed my own code changes.

---------

Signed-off-by: burgholzer <burgholzer@me.com>

Author: burgholzer

.readthedocs.yaml

@@ -37,9 +37,6 @@ build:
       # Build the MLIR documentation
       - uvx cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_MQT_CORE_MLIR=ON -DMQT_MLIR_MIN_VERSION=19.0 -DMLIR_DIR=/usr/lib/llvm-19/lib/cmake/mlir -DLLVM_DIR=/usr/lib/llvm-19/lib/cmake/llvm
       - uvx cmake --build build --target mlir-doc
-      # Remove unwanted artifacts from the MLIR documentation
-      - 'find docs/mlir -name "*.md" -exec sed -i "s@\[TOC\]@@g" {} \;'
-      - 'find docs/mlir -name "*.md" -exec sed -i "s@\[source\](https://github.com/llvm/llvm-project/.*)@@g" {} \;'
     build:
       html:
         - uv run --frozen --no-dev --group docs -m sphinx -T -b html -d docs/_build/doctrees -D language=en docs $READTHEDOCS_OUTPUT/html

CMakeLists.txt

@@ -128,7 +128,11 @@ if(BUILD_MQT_CORE_MLIR)
     POST_BUILD
     COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_CURRENT_BINARY_DIR}/docs/
             ${CMAKE_CURRENT_SOURCE_DIR}/docs/mlir/
-    COMMENT "Copying generated MLIR documentation")
+    COMMAND ${CMAKE_COMMAND} -D DOCS_DIR:PATH=${CMAKE_CURRENT_SOURCE_DIR}/docs/mlir -P
+            ${CMAKE_CURRENT_SOURCE_DIR}/cmake/CleanMLIRDocs.cmake
+    COMMENT "Copying and cleaning up generated MLIR documentation"
+    VERBATIM)
+
 endif()
 
 if(MQT_CORE_MASTER_PROJECT)

cmake/CleanMLIRDocs.cmake

@@ -0,0 +1,27 @@
+# Copyright (c) 2023 - 2025 Chair for Design Automation, TUM
+# Copyright (c) 2025 Munich Quantum Software Company GmbH
+# All rights reserved.
+#
+# SPDX-License-Identifier: MIT
+#
+# Licensed under the MIT License
+
+if(NOT DEFINED DOCS_DIR)
+  message(FATAL_ERROR "DOCS_DIR is not defined!")
+endif()
+
+file(GLOB_RECURSE MD_FILES "${DOCS_DIR}/*.md")
+foreach(MD_FILE ${MD_FILES})
+  # Read the entire file content into a single variable.
+  file(READ ${MD_FILE} CONTENT)
+
+  # Replace lines that only contain [TOC], allowing for whitespace.
+  string(REGEX REPLACE "\n\\[TOC\\]\n" "" CONTENT "${CONTENT}")
+
+  # Replace lines that only contain an llvm-project source link, allowing for whitespace.
+  string(REGEX REPLACE "\n\\[source\\]\\(https://github.com/llvm/llvm-project/blob/main.*\.td\\)\n"
+                       "" CONTENT "${CONTENT}")
+
+  # Write the processed content back to the file.
+  file(WRITE ${MD_FILE} "${CONTENT}")
+endforeach()

docs/mlir/MQTOpt.md

@@ -1,5 +1,5 @@
 ---
-hide-toc: true
+tocdepth: 3
 ---
 
 # MQTOpt Dialect
@@ -9,13 +9,6 @@ hide-toc: true
 :end-before: "## Operations"
 ```
 
-```{contents}
-:depth: 1
-:local:
-:backlinks:
-:class: this-will-duplicate-information-and-it-is-still-useful-here
-```
-
 ## Operations
 
 ```{include} Dialects/MLIRMQTOptDialect.md

docs/mlir/MQTRef.md

@@ -1,5 +1,5 @@
 ---
-hide-toc: true
+tocdepth: 3
 ---
 
 # MQTRef Dialect
@@ -9,13 +9,6 @@ hide-toc: true
 :end-before: "## Operations"
 ```
 
-```{contents}
-:depth: 1
-:local:
-:backlinks:
-:class: this-will-duplicate-information-and-it-is-still-useful-here
-```
-
 ## Operations
 
 ```{include} Dialects/MLIRMQTRefDialect.md

docs/mlir/index.md

@@ -25,7 +25,7 @@ Conversions
 This page is a work in progress.
 The content is not yet complete and subject to change.
 Contributions are welcome.
-See the {doc}`contribution guide <contributing>` for more information.
+See the {doc}`contribution guide <../contributing>` for more information.
 :::
 
 ## Classical Result Semantics

pyproject.toml

@@ -297,7 +297,6 @@ repair-wheel-command = "delvewheel repair -w {dest_dir} {wheel} --namespace-pkg
 
 [tool.uv]
 required-version = ">=0.5.20"
-reinstall-package = ["mqt-core"]
 
 [tool.uv.sources]
 mqt-core = { workspace = true }
@@ -325,6 +324,7 @@ docs = [
   "graphviz>=0.20.3",
   "sphinx>=8.1.3",
   "sphinx>=8.2.3; python_version >= '3.11'",
+  "mlir-pygments>=1.0.0",
 ]
 test = [
   "pytest>=8.3.5",