documentation: add mkdocs-based documentation (#3754)

It is time to add a docs website to xDSL. I'd like for our docs to be as
pretty as [marimo's](https://docs.marimo.io/api/), with similar
interactive elements and pretty styling. I'm not super confident in
web-things, so would love some help with styling and deploying to either
docs.xdsl.dev or xdsl.dev/docs using GH pages.

This PR adds mkdocs, adds some make commands to build and serve the docs
locally, and adds some barebones docs for the core.py file in xDSL.
In the future, it would be nice to do something like MLIR's automatic
building of docs for dialects and other parts of the codebase that are
more structured.

Makefile

@@ -11,7 +11,7 @@ VENV_DIR ?= .venv
 export UV_PROJECT_ENVIRONMENT=$(if $(VIRTUAL_ENV),$(VIRTUAL_ENV),$(VENV_DIR))
 
 # allow overriding which extras are installed
-VENV_EXTRAS ?= --extra gui --extra dev --extra jax --extra riscv
+VENV_EXTRAS ?= --extra gui --extra dev --extra jax --extra riscv --extra docs
 
 # default lit options
 LIT_OPTIONS ?= -v --order=smart
@@ -163,3 +163,13 @@ coverage-report: uv-installed
 .PHONY: coverage-clean
 coverage-clean: uv-installed
 	uv run coverage erase
+
+# docs
+
+.PHONY: docs-serve
+docs-serve: uv-installed
+	uv run mkdocs serve
+
+.PHONY: docs-build
+docs-build: uv-installed
+	uv run mkdocs build

docs/api/index.md

@@ -0,0 +1,5 @@
+# Api Reference
+
+| Module               | Name                     |
+|----------------------|--------------------------|
+| [`ir`](ir/index.md)  | IR Data Structures       |

docs/api/ir/attribute.md

@@ -0,0 +1,38 @@
+# Attribute
+
+## ::: xdsl.ir.Attribute
+
+    options:
+      members:
+        - name
+        - verify
+      show_root_heading: true
+
+## ::: xdsl.ir.Data
+
+    options:
+      members:
+        - data
+        - print_parameter
+        - parse_parameter
+      show_root_heading: true
+
+## ::: xdsl.ir.ParametrizedAttribute
+
+    options:
+      members:
+        - parameters
+        - print_parameters
+        - parse_parameters
+        - get_irdl_definition
+      show_root_heading: true
+
+## ::: xdsl.ir.TypedAttribute
+
+    options:
+      members:
+        - parameters
+        - print_parameters
+        - parse_parameters
+        - get_irdl_definition
+      show_root_heading: true

docs/api/ir/dialect.md

@@ -0,0 +1,8 @@
+
+# ::: xdsl.ir.Dialect
+
+    options:
+      members:
+        - attributes
+        - operations
+      show_root_heading: true

docs/api/ir/index.md

@@ -0,0 +1,34 @@
+# IR Data Structures
+
+## [Attribute](attribute.md)
+
+Attributes represent compile-time information in xDSL.
+All attributes are immutable, equatable, and hashable.
+
+## [SSAValue](ssa_value.md)
+
+Run-time information is represented as SSAValue.
+SSA stands for [static single-assignment](https://en.wikipedia.org/wiki/Static_single-assignment_form), meaning that each value is only ever assigned once, and never reassigned.
+This property is useful when performing transformations such as dead-code elimination, constant folding, and other compiler transformations.
+
+## [IRNode](ir_node.md)
+
+Code is represented as a recursive data structure, where [operations](operation.md) contain a doubly-linked list of [regions](region.md), which contain a doubly linked list of [blocks](block.md), which contain operations.
+
+## [Operation](operation.md)
+
+Operations are rich objects that carry some meaning in their IR.
+They can be used to represent integer addition (`arith.addi`), a module of code (`builtin.module`), a function declaration or definition (`func.func`), and many more.
+
+## [Block](block.md)
+
+Blocks are a list of operations.
+They have a (possibly empty) list of operands, that can be used to model function arguments for use in the function body, or loop arguments.
+
+## [Region](region.md)
+
+Regions are a list of blocks.
+
+## [Dialect](dialect.md)
+
+A dialect is a grouping of [attributes](attribute.md) and [operations](operation.md).

docs/api/ir/ir_node.md

@@ -0,0 +1,6 @@
+# IRNode
+
+## ::: xdsl.ir.IRNode
+
+    options:
+      show_root_heading: true

docs/api/ir/operation.md

@@ -0,0 +1,28 @@
+# Operation
+
+## ::: xdsl.ir.Operation
+
+    options:
+      members:
+        - name
+        - operands
+        - results
+        - successors
+        - properties
+        - attributes
+        - regions
+        - parent
+        - next_op
+        - prev_op
+        - traits
+      show_root_heading: true
+
+## ::: xdsl.ir.OpOperands
+
+    options:
+      show_root_heading: true
+
+## ::: xdsl.ir.OpTraits
+
+    options:
+      show_root_heading: true

docs/api/ir/ssa_value.md

@@ -0,0 +1,12 @@
+
+# SSAValue
+
+## ::: xdsl.ir.SSAValue
+
+    options:
+      show_root_heading: true
+
+## ::: xdsl.ir.Use
+
+    options:
+      show_root_heading: true

docs/index.md

@@ -0,0 +1,5 @@
+# xDSL
+
+[xDSL](https://xdsl.dev/) is a compiler framework designed to be approachable, productive, and fun to use.
+
+[API Reference](api/index.md)

mkdocs.yml

@@ -0,0 +1,15 @@
+site_name: xDSL
+
+theme:
+  name: "material"
+
+plugins:
+- search
+- mkdocstrings
+
+
+# nav:
+#   - xDSL: index.md
+#   - API Reference:
+#     - API Reference: api/index.md
+#     - Core IR Data Structures: api/ir/index.md

pyproject.toml

@@ -33,6 +33,11 @@ dev = [
     "pytest-asyncio==0.25.2",
     "pyright==1.1.392.post0",
 ]
+docs = [
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.5.49",
+    "mkdocstrings[python]>=0.27.0",
+]
 gui = ["textual==1.0.0", "pyclip==0.7"]
 jax = ["jax==0.4.38", "numpy==2.2.1"]
 riscv = ["riscemu==2.2.7"]