Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update ReadTheDocs settings file #2083

Merged
merged 14 commits into from
Jan 24, 2025
Prev Previous commit
Next Next commit
Revert "remove the custom warnings checker"
This reverts commit 071317b.
drammock committed Jan 21, 2025
commit ce874ecced111ddfa4fcfe16b1547bd962fdc4db
72 changes: 72 additions & 0 deletions tests/utils/check_warnings.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
"""Check the list of warnings produced by a doc build."""

import sys

from pathlib import Path

from colorama import Fore, init

from pydata_sphinx_theme.utils import escape_ansi


# init colors for all plateforms
init()


def check_warnings(file: Path) -> bool:
"""Check the list of warnings produced by a doc build.

Raise errors if there are unexpected ones and/or if some are missing.

Parameters:
file: the path to the generated warning.txt file from
the CI build

Returns:
0 if the warnings are all there
1 if some warning are not registered or unexpected
"""
# print some log
print("\n=== Sphinx Warnings test ===\n")

# find the file where all the known warnings are stored
warning_file = Path(__file__).parents[1] / "warning_list.txt"
extra_warning_file = Path(__file__).parents[1] / "intermittent_warning_list.txt"
Comment on lines +33 to +34
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

unrelated simplification, noticed in passing


received_warnings = escape_ansi(file.read_text()).strip().split("\n")
expected_warnings = warning_file.read_text().strip().split("\n")
intermittent_warnings = extra_warning_file.read_text().strip().split("\n")
# filter out empty warnings (happens on notebooks for some reason)
received_warnings = list(filter(len, received_warnings))

print(
f'Checking build warnings in file: "{file}" and comparing to expected '
f'warnings defined in "{warning_file}" and "{extra_warning_file}"\n\n'
)

for exp_w in expected_warnings[::-1] + intermittent_warnings[::-1]:
found = False
for rec_w in received_warnings:
if exp_w in rec_w:
received_warnings.remove(rec_w)
if exp_w in expected_warnings:
expected_warnings.remove(exp_w)
elif exp_w in intermittent_warnings:
intermittent_warnings.remove(exp_w)
found = True
break
# alert only if an *always expected* warning wasn't raised (not intermittent)
if not found and exp_w not in intermittent_warnings:
print(f"{Fore.YELLOW}Warning was not raised: {Fore.RESET}{exp_w}\n")
# warn about unexpected warnings
for rec_w in received_warnings[::-1]:
print(f"{Fore.YELLOW}Unexpected warning: {Fore.RESET}{rec_w}\n")
return len(received_warnings) or len(expected_warnings)


if __name__ == "__main__":
# cast the file to path and resolve to an absolute one
file = Path.cwd() / "warnings.txt"

# execute the test
sys.exit(check_warnings(file))
6 changes: 4 additions & 2 deletions tox.ini
Original file line number Diff line number Diff line change
@@ -108,7 +108,8 @@ extras = {[testenv:docs-no-checks]extras}
deps =
py39-sphinx61-docs: sphinx~=6.1.0
commands =
sphinx-build -b html docs/ docs/_build/html -v {posargs}
sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs}
python tests/utils/check_warnings.py

# recommended for local development, this command will build the PST documentation
# with the default Sphinx version and the PST installed in editable mode
@@ -121,7 +122,8 @@ set_env = PYDEVD_DISABLE_FILE_VALIDATION=1
extras = {[testenv:docs-no-checks]extras}
package = editable
commands =
sphinx-build -b html docs/ docs/_build/html -v {posargs}
sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs}
python tests/utils/check_warnings.py

# build the docs with live-reload, if you are working on the docs only (no theme changes) the best option is to call
# tox run -e docs-live