Adding a test framework for sphinx-simplepdf

[kreuzberger]

First implementation of a tox based test framework, trying to handle issues #112 and #120 in current versions

[kreuzberger]

Currently there is no github action to perform tests, nor are lint tests etc working. The only tests working are e.g.
tox -e py313-sphinx82
which will lead to errors due to #112.

E       assert 16 == 0
E        +  where 16 = len(["ERROR: Content discarded: target points to undefined anchor ('url', ('internal', 'document-chapter1#section-1-1'))",...ion-1-1 for internal URI reference', 'ERROR: No anchor #document-chapter1#section-1-1 for internal URI reference', ...])

[kreuzberger]

for #120 and sphinx 7.4 the tests fails cause the links associcated with Chapter 1 should lead to page 4 and the Chapter 2 links to page 5. In the current version they links to page 3/4.

      text = extract_pdf_text(pdf_path)
    
>       assert """
    Table of Contents
    
    Contents:
    
    Chapter 1: Getting Started
    
    • Section 1.1
    • Section 1.2
    
    Chapter 2: Advanced Topics
    
    • Section 2.1
    • Section 2.2
    
    4
    
    4
    
    4
    
    5
    
    5
    
    5
    """ in text

[kreuzberger]

@ubmarco any suggestions?

[kreuzberger]

This is related to #119, also introducing a pyproject.toml file.

[ubmarco]

The PR #119 got merged, please rebase this

[kreuzberger]

This branch / pull request needs a review by a real python developer. I tried to merge by best knowledge, but due to my main scope (c++) i am not sure how to handle all the stuff in pyproject.toml.
E.g. the question if the dependencies for the documents should be an extra or an group dependeny and so on.

[kreuzberger]

The relations between the demo project and the doc projects seems to be covered now, but i have no idea thats the difference between the /Sphinx-SimplePDF-DEMO.pdf and the also referenced /Sphinx-SimplePDF.pdf

Some targets now work, e.g. make test with sphinx < 8.2, some are not (e.g. make linkcheck)

[kreuzberger]

❗ should not be merged until windows tests are also successfull. currently disabled but on work....

[kreuzberger]

Looking at the main branch, i see that weasyprint also does not work there.
The build jobs results are good, but if you look at the output, you see that weasyprint crashes with segfault.

WARNING: CalledProcessError in weasyprint, retrying
Command '['weasyprint', 'D:\\a\\sphinx-simplepdf\\sphinx-simplepdf\\docs\\_build\\simplepdf\\index.html', 'D:\\a\\sphinx-simplepdf\\sphinx-simplepdf\\docs\\_build\\simplepdf\\Sphinx-SimplePDF.pdf']' returned non-zero exit status 3221225477.

[kreuzberger]

Yeah, 😀 , this was hard work 💪 but glad to finish it at the end with success 🎉

@ubmarco , @danwos : This is just a beginning if you see our discussions at #83, but you see how important even for simple tests of the extension it is helpful.

PDF Generation out of the requirement documents is not just a gimmick, from our customers’ and managers’ perspective, this is a must-have acceptance criterion ❗

[aanagnosastronauticscom]

PDF Generation out of the requirement documents is not just a gimmick, from our customers’ and managers’ perspective, this is a must-have acceptance criterion ❗

Very true, internally, i have, a 3 digit number of tests covering PDF generation.
You simply can't give HTML to a great number of corporate and government entities.

[kreuzberger]

PDF Generation out of the requirement documents is not just a gimmick, from our customers’ and managers’ perspective, this is a must-have acceptance criterion ❗

Very true, internally, i have, a 3 digit number of tests covering PDF generation. You simply can't give HTML to a great number of corporate and government entities.

We do the same, currently we use libpdf for this in our test environment for the pdfs.
To avoid inter-extension dependencies (libpdf currently has mutually exclusive dependencies) i currently use just pdfminer.six here.

If you want it could be helpful to share your experience in #83 with tips and suggestions about what and how you test

[patdhlk]

Tests are green, framework looks solid. Approving to merge now — follow-up issues will be filed for items that need attention before release.

[patdhlk]

pyproject.toml — dev tools in production dependencies

pre-commit>=3.5, pytest>=7.0, and packaging>=20.0 are in [project.dependencies]. This means anyone who pip install sphinx-simplepdf gets these installed as transitive dependencies. Dev/test tooling should stay in [dependency-groups].dev.

Additionally, packaging has a comment saying it replaces pkg_resources.parse_version, but it's not imported anywhere in the changed code — it's dead weight.

[patdhlk]

pyproject.toml — weasyprint hard pin

weasyprint==67.0 (was >=67.0). WeasyPrint 68.0 does have real breaking changes (deprecated default_url_fetcher, CVE-2025-68616 security fix), so a constraint makes sense — but an exact pin in a library's dependencies prevents users from getting security patches and causes version conflicts with other packages.

Is there a specific reason for the hard pin? If so, could you document it? Otherwise a bounded range like >=67.0,<69 would be less restrictive while still avoiding the 68.0 breakage.

[patdhlk]

simplepdf.py — logger.warning demoted to logger.info

WeasyPrint retry messages (TimeoutExpired, CalledProcessError) were changed from logger.warning() to logger.info(). In Sphinx, warnings are visible by default and become errors with -W. Info messages are still visible but won't trigger -W.

A timeout or crash during a retry is something users should see without needing verbose mode, and builds using -W should know about it. These should stay as warnings.

[patdhlk]

simplepdf.py — heading class rework is a breaking change

The heading logic removes even/odd/last classes from headings and moves them to a sibling <span>, and adds new heading-N and anchor-before-heading classes. This changes the HTML output structure — any user with custom CSS targeting h2.even, h2.last, etc. will be broken.

This should get a changelog entry and a migration note so users know what to update in their custom stylesheets.

[patdhlk]

_fonts.scss — @font-face comma syntax is broken

The font-family descriptor inside @font-face defines a single name to register, not a fallback list. Writing font-family: Fira Mono, monospace; inside @font-face does not create a fallback — it registers a literal name including the comma, which produces undefined/browser-dependent behavior.

Additionally, the first declaration uses FiraMono (no space) while the other two use Fira Mono (with space). These are different font-family names in CSS, so the regular weight would never match the bold/medium weights.

The correct approach would be to use a consistent quoted name across all three @font-face blocks:

@font-face {
    font-family: "Fira Mono";
    src: url(fonts/FiraMono-Regular.ttf);
}
@font-face {
    font-family: "Fira Mono";
    font-weight: 500;
    src: url(fonts/FiraMono-Medium.ttf);
}
@font-face {
    font-family: "Fira Mono";
    font-weight: bold;
    src: url(fonts/FiraMono-Bold.ttf);
}

Then reference it with a fallback in regular style rules: font-family: "Fira Mono", monospace;

[patdhlk]

tests/ — German comments should be translated

Several comments and docstrings are in German: Eigenen Handler OHNE Sphinx-Filter für Debug, Verhindere Doppel-Logging in conftest.py, and Extrahiere gesamten Text aus PDF, Baue das PDF und liefere... in utils.py. The codebase is English — these should be translated for consistency and readability for all contributors.

[patdhlk]

tests/ — commented-out assertion and unconditionally skipped test

test_basic_build.py line 13 has # assert not result.has_warnings() commented out — if the build produces warnings, the assertion should be adjusted to match reality, not commented out.

test_warnings.py has test_missing_image_warning that unconditionally calls pytest.skip("Requires test doc with broken image"). Either create the test fixture (it's a few lines of RST) or remove the test.

[patdhlk]

Review Summary

Thanks for the contribution — having a test framework for this project is a big step forward. The SphinxBuild helper, fixture-based approach, and the SSIM-based PDF visual regression testing are solid foundations.

A few items that should be addressed before release (see individual comments above):

Bugs:

• @font-face declarations use comma syntax that doesn't work as intended, plus inconsistent naming (FiraMono vs Fira Mono) — the regular weight won't match bold/medium

Breaking changes needing documentation:

• Heading class rework (removed even/odd/last from headings, moved to sibling <span>) needs a changelog entry and migration note

Dependency issues:

• pre-commit, pytest, packaging should not be in production [project.dependencies]
• weasyprint==67.0 hard pin needs justification or should be relaxed to a bounded range

Minor cleanup:

• German comments in test files should be translated to English
• Commented-out assertion and unconditionally skipped test should be resolved
• WeasyPrint retry log level demotion from warning to info should be reconsidered

[kreuzberger]

Thanks for the merge. I just wondered why we didn't fix the issues BEFORE the merge was done. But ok.