[MAINT] test build all test docs in strict mode

.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

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     = .

tests/Makefile

@@ -0,0 +1,15 @@
+all:
+# 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
+	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

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

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     = .

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")]

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     = .

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     = .

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
 

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"

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     = .

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     = .

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     = .

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")]

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     = .

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     = .

tests/test_autodoc.py

@@ -221,9 +221,11 @@ def test_root_auto_link_basic(app, confdict):
     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() <BaseClass.BaseClass>` - the constructor, whose description extends\n    to the next line\n* :meth:`DoBase() <BaseClass.DoBase>` - another BaseClass method\n"
+    assert method_section.rawsource == (
+        "BaseClass Methods:\n"
+        "* :meth:`BaseClass() <BaseClass.BaseClass>` - the constructor, whose description extends\n"
+        "    to the next line\n\n"
+        "DoBase - another BaseClass method\n"
     )
     assert (
         see_also_line_1.rawsource

tests/test_autodoc_short_links.py

@@ -330,11 +330,9 @@ def test_root_auto_link_basic(app, confdict):
     method_section = content[0][2][1][1][0]  # a bit fragile, I know
     assert method_section.rawsource == (
         "BaseClass Methods:\n"
-        "* :meth:`BaseClass() <BaseClass.BaseClass>` "
-        "- the constructor, whose description extends\n"
-        "    to the next line\n"
-        "* :meth:`DoBase() <BaseClass.DoBase>` "
-        "- another BaseClass method\n"
+        "* :meth:`BaseClass() <BaseClass.BaseClass>` - the constructor, whose description extends\n"
+        "    to the next line\n\n"
+        "DoBase - another BaseClass method\n"
     )
 
     see_also_line_1 = content[0][2][1][1][1]  # a bit fragile, I know