gh-136155: Docs: check for EPUB fatal errors in CI #134074
Conversation
| @@ -512,6 +512,7 @@ | |||
|
|
|||
| epub_author = 'Python Documentation Authors' | |||
| epub_publisher = 'Python Software Foundation' | |||
| epub_exclude_files = ('index.xhtml', 'download.xhtml') | |||
There was a problem hiding this comment.
For reference:
A sequence of files that are generated/copied in the build directory but should not be included in the EPUB file.
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-epub_exclude_files
There was a problem hiding this comment.
Thanks, looks good.
We'll need to wait for #136155 (comment) / sphinx-doc/sphinxext-opengraph#136 / sphinx-doc/sphinxext-opengraph#137 to be fixed before merging.
But they're taking some time. Until sphinxext-opengraph is fixed and released, is it useful to log these errors in CI, without failing? Or shall we wait a bit longer?
|
Would it be worth to add |
|
As a custom file? Probably not, because it would only be for the short term. Unlike |
I modified the PR for the case it would be useful. PS on a shelf I have a changeset to print also regular errors informationally, but I think I will wait with it until fatal errors are gone. EPUB build on my machine produces 92 errors currently and I don't want to make fatal errors to be drown out by them in the logs. |
| @@ -66,7 +66,7 @@ jobs: | |||
| run: | | |||
| set -Eeuo pipefail | |||
| # Build docs with the nit-picky option; write warnings to file | |||
| make -C Doc/ PYTHON=../python SPHINXOPTS="--quiet --nitpicky --fail-on-warning --warning-file sphinx-warnings.txt" html | |||
| make -C Doc/ PYTHON=../python SPHINXOPTS="--quiet --nitpicky --warning-file sphinx-warnings.txt" html | |||
There was a problem hiding this comment.
The redundancy can be seen in a job logs (from before the change): https://github.com/python/cpython/actions/runs/16254225968/job/45888071303
| with Path("Doc/epubcheck.txt").open(encoding="UTF-8") as f: | ||
| warnings = [warning.split(" - ") for warning in f.read().splitlines()] | ||
|
|
||
| fatal_errors = [warning for warning in warnings if warning[0] == "FATAL"] |
There was a problem hiding this comment.
Should we just call them errors?
| if not Path("Doc").exists() or not Path("Doc").is_dir(): | ||
| raise RuntimeError("Must run this script from the repo root") |
There was a problem hiding this comment.
Let's keep this closer to Doc/tools/check-warnings.py. It helps remove text duplication in tracebacks, see https://pypi.org/project/flake8-errmsg/
| if not Path("Doc").exists() or not Path("Doc").is_dir(): | |
| raise RuntimeError("Must run this script from the repo root") | |
| wrong_directory_msg = "Must run this script from the repo root" | |
| if not Path("Doc").exists() or not Path("Doc").is_dir(): | |
| raise RuntimeError(wrong_directory_msg) |
Validate EPUB documentation for not having warnings with level
FATALwhen running EPUBCheck in the CI.This should prevent issues similar to #136155 in the future.
The check will pass after rebase on #136187 merged to the main branch.