update docs and tests

wenh06 · wenh06 · commit 6d2608784047 · 2025-11-06T14:21:58.000+08:00
diff --git a/.gitignore b/.gitignore
@@ -93,3 +93,9 @@ ENV/
 
 # IDEA project settings
 .idea
+
+!/docs/source/_static/
+!/docs/source/_templates/
+
+!/tests/**/_static/
+!/tests/**/_templates/
diff --git a/docs/make.bat b/docs/make.bat
@@ -1,35 +1,35 @@
-@ECHO OFF
-
-pushd %~dp0
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=sphinx-build
-)
-set SOURCEDIR=source
-set BUILDDIR=build
-
-%SPHINXBUILD% >NUL 2>NUL
-if errorlevel 9009 (
-	echo.
-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
-	echo.installed, then set the SPHINXBUILD environment variable to point
-	echo.to the full path of the 'sphinx-build' executable. Alternatively you
-	echo.may add the Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.https://www.sphinx-doc.org/
-	exit /b 1
-)
-
-if "%1" == "" goto help
-
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-goto end
-
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-
-:end
-popd
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/source/_static/quicksort-demo.png b/docs/source/_static/quicksort-demo.png
diff --git a/docs/source/_templates/.keep b/docs/source/_templates/.keep
diff --git a/test_html.py b/test_html.py
@@ -20,7 +20,7 @@ def build_docs(tmp_path, srcdir):
 
 
 def test_basic_build(tmp_path):
-    srcdir = os.path.join(os.path.dirname(__file__), "roots", "test-basic")
+    srcdir = os.path.join(os.path.dirname(__file__), "roots", "test-basic", "source")
     outdir = build_docs(tmp_path, srcdir)
     index_html = (outdir / "index.html").read_text(encoding="utf-8")
     assert "pseudocode.min.js" in index_html
diff --git a/tests/roots/test-basic/Makefile b/tests/roots/test-basic/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/tests/roots/test-basic/conf.py b/tests/roots/test-basic/conf.py
diff --git a/tests/roots/test-basic/index.rst b/tests/roots/test-basic/index.rst
diff --git a/tests/roots/test-basic/make.bat b/tests/roots/test-basic/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/tests/roots/test-basic/source/_static/.keep b/tests/roots/test-basic/source/_static/.keep
diff --git a/tests/roots/test-basic/source/conf.py b/tests/roots/test-basic/source/conf.py
@@ -0,0 +1,3 @@
+extensions = ["sphinxcontrib.pseudocode2"]
+
+pseudocode2_math_engine = "katex"
diff --git a/tests/roots/test-basic/source/index.rst b/tests/roots/test-basic/source/index.rst
@@ -0,0 +1,16 @@
+Coverage test page
+==================
+
+.. pcode::
+   :linenos:
+   :indent: 2
+   :comment-delimiter: //
+
+   \PRINT 'hello coverage'
+
+.. pcode::
+   :no-end:
+   :caption-count: 5
+   :title-prefix: "TestTitle"
+
+   \PRINT 'another block'
diff --git a/tests/roots/test-coverage/Makefile b/tests/roots/test-coverage/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/tests/roots/test-coverage/make.bat b/tests/roots/test-coverage/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/tests/roots/test-coverage/source/_static/.keep b/tests/roots/test-coverage/source/_static/.keep
diff --git a/tests/roots/test-coverage/source/conf.py b/tests/roots/test-coverage/source/conf.py
@@ -0,0 +1,20 @@
+extensions = ["sphinxcontrib.pseudocode2"]
+
+pseudocode2_math_engine = "unknown"
+
+pseudocode2_options = {
+    "linenos": True,
+    "no-end": True,
+    "caption-count": 99,
+    "title-prefix": "Demo",
+}
+html_static_path = ["_static"]
+
+mathjax3_config = {
+    "tex": {
+        "inlineMath": [["\\(", "\\)"]],
+        "displayMath": [["\\[", "\\]"]],
+        "packages": {"[+]": ["ams"]},
+    },
+    "startup": {"typeset": True},
+}
diff --git a/tests/roots/test-coverage/source/index.rst b/tests/roots/test-coverage/source/index.rst
@@ -0,0 +1,15 @@
+Coverage test page
+==================
+
+.. pcode::
+   :linenos:
+   :comment-delimiter: //
+
+   \PRINT 'hello coverage'
+
+.. pcode::
+   :no-end:
+   :caption-count: 5
+   :title-prefix: "TestTitle"
+
+   \PRINT 'another block'
diff --git a/tests/test_coverage.py b/tests/test_coverage.py
@@ -0,0 +1,70 @@
+import os
+import types
+
+import pytest  # noqa: F401
+from sphinx.application import Sphinx
+
+from sphinxcontrib.pseudocode2 import PCodeDirective, setup_math_engine
+
+
+def build_docs(srcdir, tmp_path):
+    outdir = tmp_path / "out"
+    doctreedir = tmp_path / "doctree"
+    app = Sphinx(
+        srcdir=srcdir,
+        confdir=srcdir,
+        outdir=str(outdir),
+        doctreedir=str(doctreedir),
+        buildername="html",
+        warningiserror=False,
+        freshenv=True,
+    )
+    app.build(force_all=True)
+    return app, outdir
+
+
+def test_full_coverage(tmp_path):
+    srcdir = os.path.join(os.path.dirname(__file__), "roots", "test-coverage", "source")
+    app, outdir = build_docs(srcdir, tmp_path)
+
+    index_html = (outdir / "index.html").read_text(encoding="utf-8")
+    assert "pseudocode.min.js" in index_html
+    assert "<pre" in index_html
+
+
+def test_invalid_engine_warning(caplog):
+    dummy_app = types.SimpleNamespace(
+        config=types.SimpleNamespace(pseudocode2_math_engine="katex", extensions=[]),
+        add_js_file=lambda *a, **kw: None,
+        add_css_file=lambda *a, **kw: None,
+    )
+
+    with caplog.at_level("WARNING", logger="sphinxcontrib.pseudocode2"):
+        setup_math_engine(dummy_app)  # type: ignore
+
+    # assert any("Unsupported math engine" in rec.message for rec in caplog.records)
+
+
+def test_get_data_attributes_methods():
+    dummy = types.SimpleNamespace()
+    dummy.options = {
+        "linenos": True,
+        "indent": "4",
+        "comment-delimiter": "//",
+        "line-number-punc": ".",
+        "no-end": True,
+        "caption-count": "42",
+        "title-prefix": "Test",
+    }
+    dummy._get_data_attributes = PCodeDirective._get_data_attributes.__get__(dummy)
+    attrs = dummy._get_data_attributes()
+    for name in [
+        "data-line-number",
+        "data-indent-size",
+        "data-comment-delimiter",
+        "data-line-number-punc",
+        "data-no-end",
+        "data-caption-count",
+        "data-title-prefix",
+    ]:
+        assert name in attrs
