This is an automated email from the ASF dual-hosted git repository.
junrushao pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tvm-ffi.git
The following commit(s) were added to refs/heads/main by this push:
new 66778b5 doc: Enable Sphinx Build Checks in CI (#38)
66778b5 is described below
commit 66778b5e4fc017710d699a146f355ed48f631dca
Author: Junru Shao <[email protected]>
AuthorDate: Mon Sep 22 14:47:40 2025 -0700
doc: Enable Sphinx Build Checks in CI (#38)
This PR adds an additional stage in parallel to stage `lint`, which
builds Python docs via uv + sphinx on every commit and catches any
warning from the building process via:
```
sphinx-build -W --keep-going -b html docs docs/_build/html
```
A few issues:
- doc building right now depends on wheel building, which may add some
unnecessary CI time;
- tests for C++ doc building is not enabled yet. it seems plenty of
warnings there.
<img width="980" height="421" alt="image"
src="https://github.com/user-attachments/assets/524bb806-a58d-4592-b632-3d15fd440ff5";
/>
---
.github/workflows/ci_test.yml | 15 +++++++++++++++
docs/_stubs/cpp_index.rst | 24 ++++++++++++++++++++++++
docs/conf.py | 31 ++++++++++++++++++++++++++++++-
docs/reference/cpp/index.rst | 8 +++++---
pyproject.toml | 1 +
python/tvm_ffi/_tensor.py | 10 +++++-----
python/tvm_ffi/module.py | 6 +++---
7 files changed, 83 insertions(+), 12 deletions(-)
diff --git a/.github/workflows/ci_test.yml b/.github/workflows/ci_test.yml
index 9787d5c..91f6bbd 100644
--- a/.github/workflows/ci_test.yml
+++ b/.github/workflows/ci_test.yml
@@ -52,6 +52,21 @@ jobs:
- uses: actions/checkout@v4
- uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd #
v3.0.1
+ doc:
+ needs: [lint, prepare]
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ submodules: recursive
+ - name: Set up uv
+ uses: astral-sh/setup-uv@b75a909f75acd358c2196fb9a5f1299a9a8868a4 #
v6.7.0
+ with:
+ python-version: 3.13
+ - name: Generate docs
+ run: |
+ uv run --group docs sphinx-build -W --keep-going -b html docs
docs/_build/html
+
test:
needs: [lint, prepare]
if: >
diff --git a/docs/_stubs/cpp_index.rst b/docs/_stubs/cpp_index.rst
new file mode 100644
index 0000000..766de11
--- /dev/null
+++ b/docs/_stubs/cpp_index.rst
@@ -0,0 +1,24 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+.. http://www.apache.org/licenses/LICENSE-2.0
+
+.. Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+==============
+Full API Index
+==============
+
+This page contains stub C++ API indexs to avoid Sphinx warning in CI testing.
+If you see this page, it means the C++ API docs are not generated via Doxygen.
+Follow the instructions in `docs/reference/cpp/README.md` to generate the C++
API docs.
diff --git a/docs/conf.py b/docs/conf.py
index b4188fe..69df5ca 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -20,6 +20,7 @@
import os
from pathlib import Path
+import sphinx
import tomli
os.environ["TVM_FFI_BUILD_DOCS"] = "1"
@@ -124,6 +125,34 @@ intersphinx_mapping = {
"torch": ("https://pytorch.org/docs/stable";, None),
}
+_DOCS_DIR = Path(__file__).resolve().parent
+_STUBS = {
+ "_stubs/cpp_index.rst": "reference/cpp/generated/index.rst",
+}
+
+
+def _prepare_stub_files() -> None:
+ """Move stub files into place if they do not already exist."""
+ for src, dst in _STUBS.items():
+ src_path = _DOCS_DIR / src
+ dst_path = _DOCS_DIR / dst
+ dst_path.parent.mkdir(parents=True, exist_ok=True)
+ if not dst_path.exists():
+ dst_path.write_text(src_path.read_text(encoding="utf-8"),
encoding="utf-8")
+
+
+def _apply_config_overrides(_: object, config: object) -> None:
+ """Apply runtime configuration overrides derived from environment
variables."""
+ config.build_exhale = build_exhale
+
+
+def setup(app: sphinx.application.Sphinx) -> None:
+ """Register custom Sphinx configuration values."""
+ _prepare_stub_files()
+ app.add_config_value("build_exhale", build_exhale, "env")
+ app.connect("config-inited", _apply_config_overrides)
+
+
autodoc_mock_imports = ["torch"]
autodoc_default_options = {
"members": True,
@@ -143,7 +172,7 @@ source_suffix = {".rst": "restructuredtext", ".md":
"markdown"}
language = "en"
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "README.md"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "README.md", "_stubs"]
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = "sphinx"
diff --git a/docs/reference/cpp/index.rst b/docs/reference/cpp/index.rst
index ac9b1d7..d35bbfc 100644
--- a/docs/reference/cpp/index.rst
+++ b/docs/reference/cpp/index.rst
@@ -101,7 +101,9 @@ Key Classes
Full API Index
--------------
-.. toctree::
- :maxdepth: 2
+.. ifconfig:: build_exhale
- generated/index.rst
+ .. toctree::
+ :maxdepth: 2
+
+ generated/index
diff --git a/pyproject.toml b/pyproject.toml
index 58d394a..c7e43db 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -65,6 +65,7 @@ docs = [
"sphinxcontrib-mermaid",
"sphinxcontrib-napoleon==0.7",
"sphinxcontrib_httpdomain==1.8.1",
+ "setuptools<81",
"tomli",
"urllib3>=2.5.0",
]
diff --git a/python/tvm_ffi/_tensor.py b/python/tvm_ffi/_tensor.py
index 0d44994..512ba44 100644
--- a/python/tvm_ffi/_tensor.py
+++ b/python/tvm_ffi/_tensor.py
@@ -36,12 +36,12 @@ from .core import (
@registry.register_object("ffi.Shape")
class Shape(tuple, PyNativeObject):
- """Shape tuple that represents `ffi::Shape` returned by a ffi call.
+ """Shape tuple that represents ``ffi::Shape`` returned by an FFI call.
- Note:
- ----
- This class subclasses `tuple` so it can be used in most places where
- tuple is used in python array apis.
+ Notes
+ -----
+ This class subclasses :class:`tuple` so it can be used in most places where
+ :class:`tuple` is used in Python array APIs.
"""
diff --git a/python/tvm_ffi/module.py b/python/tvm_ffi/module.py
index 768463d..9503900 100644
--- a/python/tvm_ffi/module.py
+++ b/python/tvm_ffi/module.py
@@ -38,8 +38,8 @@ class ModulePropertyMask(IntEnum):
class Module(core.Object):
"""Module container for dynamically loaded Module.
- Example:
- -------
+ Examples
+ --------
.. code-block:: python
import tvm_ffi
@@ -49,7 +49,7 @@ class Module(core.Object):
# you can use mod.func_name to call the exported function
mod.func_name(*args)
- See Also:
+ See Also
--------
:py:func:`tvm_ffi.load_module`
