Skip to content

Commit 42a154a

Browse files
PragmaTwicePragmaTwice
authored
Add sphinx docs for python bindings and scripts for CI (#235)
It closes #97. This PR adds sphinx to generate API documentation for python bindings. It is achieved via the [sphinx-autoapi](https://github.com/readthedocs/sphinx-autoapi) since there are several issues while the vanilla sphinx is used for MLIR python (mostly due to namespace package and importing). If the workflow runs without errors (that's what I expect, although in most cases we need some interactive rounds to debug the workflow) and after this PR is merged, the API docs should be available in https://mlir.llvm.org/python-bindings/. cc @jpienaar @joker-eph @makslevental
1 parent 36885c8 commit 42a154a

File tree

7 files changed

+132
-4
lines changed

7 files changed

+132
-4
lines changed

‎.github/workflows/main.yml‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -44,26 +44,36 @@ jobs:
4444
run: |
4545
mkdir llvm_src/build
4646
cd llvm_src/build
47+
pip install -r ../mlir/python/requirements.txt
4748
# Assert mode is needed for the pattern search index
48-
cmake ../llvm \
49+
cmake ../llvm -GNinja \
4950
-DCMAKE_BUILD_TYPE=Release \
5051
-DLLVM_ENABLE_ASSERTIONS=ON \
5152
-DLLVM_ENABLE_PROJECTS=mlir \
5253
-DLLVM_TARGETS_TO_BUILD="host" \
5354
-DMLIR_INCLUDE_DOCS="true" \
54-
-DLLVM_ENABLE_DOXYGEN="true"
55-
make -j$(nproc) mlir-doc doxygen-mlir
55+
-DLLVM_ENABLE_DOXYGEN="true" \
56+
-DMLIR_ENABLE_BINDINGS_PYTHON=ON
57+
ninja -j$(nproc) mlir-doc doxygen-mlir MLIRPythonModules
58+
echo "PYTHONPATH=$(pwd)/tools/mlir/python_packages/mlir_core" >> $GITHUB_ENV
5659
5760
- name: Install docs
5861
run: ./mlir-www-helper.sh --install-docs "llvm_src" "website"
5962

63+
- name: Install python bindings docs
64+
run: |
65+
cd sphinx-mlir-python
66+
pip install -r requirements.txt
67+
make html
68+
cp -r _build/html ../website/static/python-bindings
69+
6070
- name: Build pattern search index
6171
run: |
6272
cd llvm_src/build
6373
# Run the tests once to ensure they are passing.
6474
# The next run used to generate the patterns log is disabling error checking. This first
6575
# run will ensure we don't generate the website when tests are broken.
66-
make -j$(nproc) check-mlir
76+
ninja -j$(nproc) check-mlir
6777
echo "finished building tests"
6878
# ignore nonzero exit codes in this command, since MLIR_GENERATE_PATTERN_CATALOG
6979
# implicitly enables`--mlir-disable-threading` which some tests are incompatible with.

‎sphinx-mlir-python/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
/_build/

‎sphinx-mlir-python/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎sphinx-mlir-python/conf.py‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
# -- Project information -----------------------------------------------------
7+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
8+
9+
project = 'MLIR Python bindings'
10+
copyright = '2025, MLIR authors'
11+
author = 'MLIR authors'
12+
13+
# -- General configuration ---------------------------------------------------
14+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
15+
16+
extensions = [
17+
'autoapi.extension'
18+
]
19+
20+
templates_path = ['_templates']
21+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
22+
23+
24+
# -- Options for HTML output -------------------------------------------------
25+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
26+
27+
html_theme = 'furo'
28+
html_static_path = ['_static']
29+
30+
# -- Options and custom logic for autoapi extension --------------------------
31+
# https://sphinx-autoapi.readthedocs.io/en/latest/reference/config.html
32+
33+
import os
34+
import mlir
35+
36+
autoapi_dirs = list(mlir.__path__)
37+
autoapi_python_use_implicit_namespaces = True
38+
39+
40+
def ensure_mlir_index(_):
41+
mlir_dir = os.path.join(os.path.dirname(__file__), "autoapi/mlir")
42+
os.makedirs(mlir_dir, exist_ok=True)
43+
mlir_index = os.path.join(mlir_dir, "index.rst")
44+
with open(mlir_index, "w", encoding="utf-8") as f:
45+
f.write("mlir namespace\n===============\n\n.. toctree::\n :maxdepth: 2\n :glob:\n\n **\n")
46+
47+
48+
def setup(app):
49+
app.connect("builder-inited", ensure_mlir_index)

‎sphinx-mlir-python/index.rst‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
MLIR Python bindings API documentation
2+
==================================
3+
4+
Welcome to the MLIR Python bindings API documentation.
5+
This website is generated from MLIR Python source code and type stubs.
6+
7+
.. toctree::
8+
:maxdepth: 2
9+
10+
autoapi/mlir/index

‎sphinx-mlir-python/make.bat‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=.
11+
set BUILDDIR=_build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎sphinx-mlir-python/requirements.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
sphinx
2+
sphinx-autoapi
3+
furo

0 commit comments

Comments
 (0)