From bede6b1e67d8ca7456759474948d7fbb18ca16e3 Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Sun, 11 Jan 2026 09:57:05 +0100 Subject: [PATCH 1/4] set doc build to fail on warning --- docs/Makefile | 2 +- tests/Makefile | 14 ++++++++++++++ tests/roots/test_autodoc/BaseClass.m | 1 + tests/roots/test_autodoc/Makefile | 2 +- tests/roots/test_classfolder/Makefile | 2 +- tests/roots/test_duplicate_link/Makefile | 2 +- tests/roots/test_no_matlab_src_dir/Makefile | 2 +- tests/roots/test_numad/Makefile | 2 +- tests/roots/test_package_links/Makefile | 2 +- tests/roots/test_package_prefix/Makefile | 2 +- tests/roots/test_pymat/Makefile | 2 +- 11 files changed, 24 insertions(+), 9 deletions(-) create mode 100644 tests/Makefile diff --git a/docs/Makefile b/docs/Makefile index b657d667..c4b93ae1 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -2,7 +2,7 @@ # # You can set these variables from the command line. -SPHINXOPTS = +SPHINXOPTS = --verbose --color --fail-on-warning SPHINXBUILD = sphinx-build SPHINXPROJ = sphinxcontrib-matlabdomain SOURCEDIR = . diff --git a/tests/Makefile b/tests/Makefile new file mode 100644 index 00000000..a0f40a5c --- /dev/null +++ b/tests/Makefile @@ -0,0 +1,14 @@ +all: +# Run all doc builds in the tests folder + make -C test_docs html + make -C roots/test_autodoc/ html + make -C roots/test_classfolder/ html + make -C roots/test_duplicate_link/ html + make -C roots/test_module_class_names/ html + make -C roots/test_no_matlab_src_dir/ html + make -C roots/test_numad/ html + make -C roots/test_package_links/ html + make -C roots/test_package_prefix/ html + make -C roots/test_pymat/ html + make -C roots/test_pymat_common_root/ html + make -C roots/test_skipping_module_members/ html diff --git a/tests/roots/test_autodoc/BaseClass.m b/tests/roots/test_autodoc/BaseClass.m index b4341075..1de9bad9 100644 --- a/tests/roots/test_autodoc/BaseClass.m +++ b/tests/roots/test_autodoc/BaseClass.m @@ -4,6 +4,7 @@ % BaseClass Methods: % BaseClass - the constructor, whose description extends % to the next line +% % DoBase - another BaseClass method % % See Also diff --git a/tests/roots/test_autodoc/Makefile b/tests/roots/test_autodoc/Makefile index 3f9c69ab..dbab22e9 100644 --- a/tests/roots/test_autodoc/Makefile +++ b/tests/roots/test_autodoc/Makefile @@ -2,7 +2,7 @@ # # You can set these variables from the command line. -SPHINXOPTS = +SPHINXOPTS = --verbose --color --fail-on-warning SPHINXBUILD = sphinx-build SPHINXPROJ = test_autodoc SOURCEDIR = . diff --git a/tests/roots/test_classfolder/Makefile b/tests/roots/test_classfolder/Makefile index 697294a3..c599b8f1 100644 --- a/tests/roots/test_classfolder/Makefile +++ b/tests/roots/test_classfolder/Makefile @@ -2,7 +2,7 @@ # # You can set these variables from the command line. -SPHINXOPTS = +SPHINXOPTS = --verbose --color --fail-on-warning SPHINXBUILD = sphinx-build SPHINXPROJ = test_classfolder SOURCEDIR = . diff --git a/tests/roots/test_duplicate_link/Makefile b/tests/roots/test_duplicate_link/Makefile index b657d667..c4b93ae1 100644 --- a/tests/roots/test_duplicate_link/Makefile +++ b/tests/roots/test_duplicate_link/Makefile @@ -2,7 +2,7 @@ # # You can set these variables from the command line. -SPHINXOPTS = +SPHINXOPTS = --verbose --color --fail-on-warning SPHINXBUILD = sphinx-build SPHINXPROJ = sphinxcontrib-matlabdomain SOURCEDIR = . diff --git a/tests/roots/test_no_matlab_src_dir/Makefile b/tests/roots/test_no_matlab_src_dir/Makefile index 3f9c69ab..dbab22e9 100644 --- a/tests/roots/test_no_matlab_src_dir/Makefile +++ b/tests/roots/test_no_matlab_src_dir/Makefile @@ -2,7 +2,7 @@ # # You can set these variables from the command line. -SPHINXOPTS = +SPHINXOPTS = --verbose --color --fail-on-warning SPHINXBUILD = sphinx-build SPHINXPROJ = test_autodoc SOURCEDIR = . diff --git a/tests/roots/test_numad/Makefile b/tests/roots/test_numad/Makefile index 3f9c69ab..dbab22e9 100644 --- a/tests/roots/test_numad/Makefile +++ b/tests/roots/test_numad/Makefile @@ -2,7 +2,7 @@ # # You can set these variables from the command line. -SPHINXOPTS = +SPHINXOPTS = --verbose --color --fail-on-warning SPHINXBUILD = sphinx-build SPHINXPROJ = test_autodoc SOURCEDIR = . diff --git a/tests/roots/test_package_links/Makefile b/tests/roots/test_package_links/Makefile index 3f9c69ab..dbab22e9 100644 --- a/tests/roots/test_package_links/Makefile +++ b/tests/roots/test_package_links/Makefile @@ -2,7 +2,7 @@ # # You can set these variables from the command line. -SPHINXOPTS = +SPHINXOPTS = --verbose --color --fail-on-warning SPHINXBUILD = sphinx-build SPHINXPROJ = test_autodoc SOURCEDIR = . diff --git a/tests/roots/test_package_prefix/Makefile b/tests/roots/test_package_prefix/Makefile index 3f9c69ab..dbab22e9 100644 --- a/tests/roots/test_package_prefix/Makefile +++ b/tests/roots/test_package_prefix/Makefile @@ -2,7 +2,7 @@ # # You can set these variables from the command line. -SPHINXOPTS = +SPHINXOPTS = --verbose --color --fail-on-warning SPHINXBUILD = sphinx-build SPHINXPROJ = test_autodoc SOURCEDIR = . diff --git a/tests/roots/test_pymat/Makefile b/tests/roots/test_pymat/Makefile index 3f9c69ab..dbab22e9 100644 --- a/tests/roots/test_pymat/Makefile +++ b/tests/roots/test_pymat/Makefile @@ -2,7 +2,7 @@ # # You can set these variables from the command line. -SPHINXOPTS = +SPHINXOPTS = --verbose --color --fail-on-warning SPHINXBUILD = sphinx-build SPHINXPROJ = test_autodoc SOURCEDIR = . From dad916c773a548bf93ff5a6425ac4eb47c8efa51 Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Sun, 11 Jan 2026 18:37:20 +0100 Subject: [PATCH 2/4] [MAINT] test build all test docs in strict mode --- .github/workflows/python-package.yml | 22 +++++++++++++++++++ tests/Makefile | 3 ++- tests/roots/test_autodoc/conf.py | 2 ++ tests/roots/test_autodoc/target/readme.txt | 3 --- .../test_duplicate_link/_src/+replab/Domain.m | 2 +- tests/roots/test_duplicate_link/conf.py | 2 ++ tests/roots/test_package_links/conf.py | 2 ++ 7 files changed, 31 insertions(+), 5 deletions(-) delete mode 100644 tests/roots/test_autodoc/target/readme.txt diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-package.yml index 3e66bd44..22a0d222 100644 --- a/.github/workflows/python-package.yml +++ b/.github/workflows/python-package.yml @@ -71,6 +71,28 @@ jobs: name: ${{ matrix.os }}_${{ matrix.python-version }}_${{matrix.sphinx-version}}_htmlcov path: htmlcov + check_test_docs: + + name: "Build all 'test docs' in strict mode to make sure they run without warning" + + runs-on: "ubuntu-latest" + + steps: + - uses: actions/checkout@v6 + + - name: Set up Python + uses: actions/setup-python@v6 + with: + python-version: 3.10 + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + python -m pip install . + + - name: Build all tests docs + run: make -C tests all + build-n-publish: if: startsWith(github.ref, 'refs/tags') && github.repository == 'sphinx-contrib/matlabdomain' name: Build and publish Python 🐍 distributions 📦 to PyPI diff --git a/tests/Makefile b/tests/Makefile index a0f40a5c..23b69d5c 100644 --- a/tests/Makefile +++ b/tests/Makefile @@ -1,5 +1,6 @@ all: -# Run all doc builds in the tests folder +# Run all doc builds in the tests folder: +# acts a bit as en end-to-end test make -C test_docs html make -C roots/test_autodoc/ html make -C roots/test_classfolder/ html diff --git a/tests/roots/test_autodoc/conf.py b/tests/roots/test_autodoc/conf.py index d45230cf..13f1f9a6 100644 --- a/tests/roots/test_autodoc/conf.py +++ b/tests/roots/test_autodoc/conf.py @@ -4,3 +4,5 @@ extensions = ["sphinx.ext.autodoc", "sphinxcontrib.matlab"] primary_domain = "mat" nitpicky = True +# ignore warning about inheriting from unknown 'handle' class +nitpick_ignore = [("mat:class", "handle")] diff --git a/tests/roots/test_autodoc/target/readme.txt b/tests/roots/test_autodoc/target/readme.txt deleted file mode 100644 index b27172a8..00000000 --- a/tests/roots/test_autodoc/target/readme.txt +++ /dev/null @@ -1,3 +0,0 @@ -Here we test basic entities that can be documented - -* diff --git a/tests/roots/test_duplicate_link/_src/+replab/Domain.m b/tests/roots/test_duplicate_link/_src/+replab/Domain.m index 9bdfa856..c4868d39 100644 --- a/tests/roots/test_duplicate_link/_src/+replab/Domain.m +++ b/tests/roots/test_duplicate_link/_src/+replab/Domain.m @@ -1,7 +1,7 @@ classdef Domain % Describes a set of elements with a common structure % -% Those elements can be compared (`.eqv`), and random elements can be produced (`.sample`). +% Those elements can be compared (`.eqv`). methods % ABSTRACT diff --git a/tests/roots/test_duplicate_link/conf.py b/tests/roots/test_duplicate_link/conf.py index 54872c11..a8a935e6 100644 --- a/tests/roots/test_duplicate_link/conf.py +++ b/tests/roots/test_duplicate_link/conf.py @@ -10,4 +10,6 @@ matlab_keep_package_prefix = True matlab_src_dir = f"{os.path.dirname(os.path.abspath(f'{__file__}/'))}/_src" nitpicky = True +# ignore warning about inheriting from unknown 'replab.CompactGroup' class +nitpick_ignore = [("mat:class", "replab.CompactGroup")] primary_domain = "mat" diff --git a/tests/roots/test_package_links/conf.py b/tests/roots/test_package_links/conf.py index 59aa6efe..f2b9ab94 100644 --- a/tests/roots/test_package_links/conf.py +++ b/tests/roots/test_package_links/conf.py @@ -6,3 +6,5 @@ matlab_keep_package_prefix = True primary_domain = "mat" nitpicky = True +# ignore warning about inheriting from unknown 'handle' class +nitpick_ignore = [("mat:class", "handle")] From c70ed99f90094da7d0aba56719c4afbf06554a9b Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Sun, 11 Jan 2026 18:42:10 +0100 Subject: [PATCH 3/4] typo --- .github/workflows/python-package.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-package.yml index 22a0d222..786258ed 100644 --- a/.github/workflows/python-package.yml +++ b/.github/workflows/python-package.yml @@ -83,7 +83,7 @@ jobs: - name: Set up Python uses: actions/setup-python@v6 with: - python-version: 3.10 + python-version: "3.10" - name: Install dependencies run: | From 1a3ca5769d43a488bd30dd8c73759ee846cf6d0f Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Sun, 11 Jan 2026 19:42:14 +0100 Subject: [PATCH 4/4] fix --- tests/test_autodoc.py | 8 +++++--- tests/test_autodoc_short_links.py | 8 +++++--- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py index 391c6a08..f42ce879 100644 --- a/tests/test_autodoc.py +++ b/tests/test_autodoc.py @@ -283,9 +283,11 @@ def test_root_auto_link_basic(make_app, rootdir): see_also_line_1 = content[0][2][1][1][1] # a bit fragile, I know see_also_line_2 = content[0][4][1][1][0] # a bit fragile, I know assert len(content) == 1 - assert ( - method_section.rawsource - == "BaseClass Methods:\n* :meth:`BaseClass() ` - the constructor, whose description extends\n to the next line\n* :meth:`DoBase() ` - another BaseClass method\n" + assert method_section.rawsource == ( + "BaseClass Methods:\n" + "* :meth:`BaseClass() ` - the constructor, whose description extends\n" + " to the next line\n\n" + "DoBase - another BaseClass method\n" ) assert ( see_also_line_1.rawsource diff --git a/tests/test_autodoc_short_links.py b/tests/test_autodoc_short_links.py index 8f6c73c2..510d3084 100644 --- a/tests/test_autodoc_short_links.py +++ b/tests/test_autodoc_short_links.py @@ -274,9 +274,11 @@ def test_root_auto_link_basic(make_app, rootdir): see_also_line_1 = content[0][2][1][1][1] # a bit fragile, I know see_also_line_2 = content[0][4][1][1][0] # a bit fragile, I know assert len(content) == 1 - assert ( - method_section.rawsource - == "BaseClass Methods:\n* :meth:`BaseClass() ` - the constructor, whose description extends\n to the next line\n* :meth:`DoBase() ` - another BaseClass method\n" + assert method_section.rawsource == ( + "BaseClass Methods:\n" + "* :meth:`BaseClass() ` - the constructor, whose description extends\n" + " to the next line\n\n" + "DoBase - another BaseClass method\n" ) assert ( see_also_line_1.rawsource