Adding a test framework for sphinx-simplepdf

.github/workflows/ci.yaml

@@ -49,17 +49,48 @@ jobs:
       - name: Set up Python
         run: uv python install ${{ matrix.python }}
       - name: Install docs dependencies
-        run: uv sync --extra docs
+        run: uv sync --group docs
       - name: Build docs (${{ matrix.target }})
         run: uv run sphinx-build -M ${{ matrix.builder }} docs docs/_build
         shell: bash
         env:
           PATH: ${{ runner.os == 'Windows' && 'C:\msys64\mingw64\bin;' || '' }}${{ env.PATH }}
+  tests:
+    name: tests-${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install WeasyPrint dependencies (Ubuntu)
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0 libffi-dev libcairo2
+      - name: Install WeasyPrint dependencies (macOS)
+        if: runner.os == 'macOS'
+        run: brew install pango libffi
+      - name: Install WeasyPrint dependencies (Windows)
+        if: runner.os == 'Windows'
+        run: |
+          $env:PATH = "C:\msys64\mingw64\bin;$env:PATH"
+          C:\msys64\usr\bin\pacman -S --noconfirm mingw-w64-x86_64-pango mingw-w64-x86_64-gdk-pixbuf2
+        shell: pwsh
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Install tests dependencies
+        run: uv sync --group dev
+      - name: Testing (${{ matrix.os }})
+        run: uv run tox
+        shell: bash
+        env:
+          PATH: ${{ runner.os == 'Windows' && 'C:\msys64\mingw64\bin;' || '' }}${{ env.PATH }}
   all_good:
     if: ${{ !cancelled() }}
     needs:
       - pre-commit
       - docs
+      - tests
     runs-on: ubuntu-latest
     steps:
       - name: Decide whether the needed jobs succeeded or failed

Makefile

@@ -32,27 +32,36 @@ lint format:
 
 .PHONY: test
 test:
-	uv run pytest -n auto || test $$? -eq 5
+	uv sync --group dev && uv run pytest
 
 .PHONY: test-matrix
 test-matrix:
-	uv run nox
+	uv sync --group dev && uv run tox
 
 .PHONY: coverage
 coverage:
 	uv run pytest --cov=sphinx_simplepdf --cov-report=html --cov-report=term || test $$? -eq 5
 
+.PHONY: docs-demo
+docs-demo:
+	uv sync --group demo && uv run sphinx-build -M simplepdf demo demo/_build
+
+.PHONY: docs-demo-deploy
+docs-demo-deploy: docs-demo
+	mkdir -p docs/_build
+	cp demo/_build/simplepdf/Sphinx-SimplePDF-DEMO.pdf docs/_static
+
 .PHONY: docs-html
-docs-html:
-	uv sync --extra docs && uv run sphinx-build -M html docs docs/_build
+docs-html: docs-demo-deploy
+	uv sync --group docs && uv run sphinx-build -M html docs docs/_build
 
 .PHONY: docs-pdf
-docs-pdf:
-	uv sync --extra docs && $(WEASYPRINT_ENV) uv run sphinx-build -M simplepdf docs docs/_build
+docs-pdf: docs-demo-deploy
+	uv sync --group docs && $(WEASYPRINT_ENV) uv run sphinx-build -M simplepdf docs docs/_build
 
 .PHONY: docs-linkcheck
-docs-linkcheck:
-	uv sync --extra docs && uv run sphinx-build -M linkcheck docs docs/_build
+docs-linkcheck: docs-demo-deploy
+	uv sync --group docs && uv run sphinx-build -M linkcheck docs docs/_build
 
 .PHONY: install
 install:

docs/directives.rst

@@ -96,7 +96,7 @@ The following chapter should only be visible in the PDF version of this document
 
 .. if-include:: simplepdf
 
-   ./if_pdf_include.rst
+   .. include:: if_pdf_include.rst
 
 .. _pdf-include:
 

docs/index.rst

@@ -57,6 +57,22 @@ Showcase
        directives
        css
        tech_details
+       examples/sphinx_needs
+       changelog
+       license
+
+.. if-builder:: linkcheck
+
+    .. toctree::
+
+       quickstart
+       installation
+       building
+       configuration
+       directives
+       css
+       tech_details
+       examples/sphinx_needs
        changelog
        license
 

pyproject.toml

@@ -7,9 +7,9 @@ name = "sphinx-simplepdf"
 version = "1.7.0"
 description = "An easy to use PDF Builder for Sphinx with a modern PDF-Theme."
 readme = "README.rst"
-license = "MIT"
-authors = [{ name = "team useblocks", email = "info@useblocks.com" }]
+license = { text = "MIT" }
 requires-python = ">=3.10"
+authors = [{ name = "team useblocks", email = "info@useblocks.com" }]
 classifiers = [
   "Framework :: Sphinx",
   "Framework :: Sphinx :: Extension",
@@ -24,7 +24,15 @@ classifiers = [
   "Topic :: Documentation",
   "Topic :: Software Development :: Documentation",
 ]
-dependencies = ["sphinx", "weasyprint>=67.0", "libsass", "beautifulsoup4"]
+dependencies = [
+  "pre-commit>=3.5",
+  "sphinx>=7.0",
+  "weasyprint==67.0",
+  "libsass",
+  "beautifulsoup4",
+  "packaging>=20.0",  # Modern replacement for pkg_resources.parse_version
+  "pytest>=7.0",
+]
 
 [project.urls]
 Homepage = "https://sphinx-simplepdf.readthedocs.io"
@@ -37,24 +45,34 @@ simplepdf_theme = "sphinx_simplepdf.themes.simplepdf_theme"
 [project.entry-points."sphinx.builders"]
 simplepdf = "sphinx_simplepdf.builders.simplepdf"
 
-[project.optional-dependencies]
-test = ["nox", "pytest", "pytest-xdist", "pytest-cov"]
+# [project.optional-dependencies]
+[dependency-groups]
+dev = [
+  "pytest>=7.0",
+  "pytest-xdist>=3.0",
+  "pytest-cov",
+  "tox>=4.0",
+  "tox-uv>=1.0",
+  "ruff>=0.4.0",
+  "pdfminer.six>=20220319",
+  "PyMuPDF>=1.24.0",        # PDF -> Image for comparison
+  "opencv-python>=4.8.0",   # cv2 for image processing
+  "scikit-image>=0.22.0",   # ssim from skimage.metrics
+]
 docs = [
+  "sphinx>=7.0,<8.2",
+  "sphinxcontrib-plantuml",
+  "sphinx-needs",
   "sphinx-copybutton",
   "sphinx-design",
   "sphinx-immaterial",
-  "sphinx-needs",
-  "sphinxcontrib-plantuml",
 ]
 
-[dependency-groups]
-dev = [
-  "pre-commit~=3.0",
-  "nox>=2025.2.9",
-  "mypy>=1.16.0",
-  "pytest",
-  "pytest-xdist",
-  "pytest-cov",
+demo = [
+  "sphinx>=7.0,<8.2",
+  "sphinxcontrib-plantuml",
+  "sphinx-needs",
+  "sphinx-copybutton",
 ]
 
 [tool.flit.module]
@@ -75,26 +93,108 @@ line-length = 120
 target-version = "py310"
 
 [tool.ruff.lint]
-select = [
-  "E",   # pycodestyle errors
-  "W",   # pycodestyle warnings
-  "F",   # pyflakes
-  "I",   # isort
-  "UP",  # pyupgrade
+extend-select = [
   "B",   # flake8-bugbear
   "C4",  # flake8-comprehensions
-  "RUF", # ruff-specific rules
-]
-ignore = [
-  "E501", # line too long (handled by formatter)
+  "F",   # pyflakes (includes unused imports)
+  "I",   # isort
+  "ICN", # flake8-import-conventions
+  "ISC", # flake8-implicit-str-concat
+  "N",   # pep8-naming
+  "RUF", # Ruff-specific rules
+  "SIM", # flake8-simplify
+  "UP",  # pyupgrade
 ]
 
+extend-ignore = ["B904", "ISC001", "ICN001", "N818", "RUF012"]
+
 [tool.ruff.lint.isort]
 known-first-party = ["sphinx_simplepdf"]
+force-sort-within-sections = true
+
+[tool.tox]
+# To use tox, see https://tox.readthedocs.io
+# $ pipx install tox
+# it is suggested to use with https://github.com/tox-dev/tox-uv or https://github.com/tox-dev/tox-conda
+# $ pipx inject tox tox-uv
+
+legacy_tox_ini = """
+[tox]
+env_list =
+    lint
+    py{311,312,313}-sphinx{74,81} #82 not working, see https://github.com/sphinx-doc/sphinx/pull/13739
+requires =
+    tox>=4
+    tox-uv>=1.0
+
+[testenv]
+deps =
+    sphinx>=7.0,<8.2
+    pytest
+    pdfminer.six>=20220319
+    sphinx-simplepdf @ .
+commands =
+    pytest {posargs:tests/}
+
+[testenv:py{310,311,312,313}-sphinx74]
+deps =
+    sphinx>=7.4,<7.5
+    pytest
+    pdfminer.six>=20220319
+    PyMuPDF>=1.24.0
+    opencv-python>=4.8.0
+    scikit-image>=0.22.0
+    sphinx-simplepdf @ .
+commands =
+    pytest {posargs:tests/}
+
+[testenv:py{311,312,313}-sphinx81]
+deps =
+    sphinx>=8.1,<8.2
+    pytest
+    pdfminer.six>=20220319
+    PyMuPDF>=1.24.0
+    opencv-python>=4.8.0
+    scikit-image>=0.22.0
+    sphinx-simplepdf @ .
+commands =
+    pytest {posargs:tests/}
+
+[testenv:py{311,312,313}-sphinx82]
+deps =
+    sphinx>=8.2,<8.3
+    pytest
+    pdfminer.six>=20220319
+    PyMuPDF>=1.24.0
+    opencv-python>=4.8.0
+    scikit-image>=0.22.0
+    sphinx-simplepdf @ .
+commands =
+    pytest {posargs:tests/}
+
+[testenv:lint]
+description = Run code quality checks
+allowlist_externals =
+    ruff
+deps =
+    ruff>=0.4.0
+commands =
+    ruff check sphinx_simplepdf/
+    ruff format --check sphinx_simplepdf/
+
+"""
+
+# [tool.setuptools.packages.find]
+# where = ["sphinx_simplepdf/themes/simplepdf_theme"]
 
-[tool.pytest.ini_options]
-testpaths = ["tests"]
-norecursedirs = [".venv", "docs", "demo"]
+# [tool.setuptools.package-data]
+# sphinx_simplepdf=[
+#     'theme.conf',
+#     '*.html',
+#     'static/styles/*.css',
+#     'static/js/*.js',
+#     'static/fonts/*.*'
+# ]
 
 [tool.mypy]
 python_version = "3.12"