From c1130c59847ba5d28182a22c4366d013ad5f7000 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Wed, 18 Dec 2024 09:35:45 -0600 Subject: [PATCH 01/14] update RTD config --- readthedocs.yml | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/readthedocs.yml b/readthedocs.yml index 5f057c9ae..0beb32d8d 100644 --- a/readthedocs.yml +++ b/readthedocs.yml @@ -1,12 +1,13 @@ version: 2 + formats: - htmlzip # build with latest available ubuntu version build: - os: ubuntu-20.04 + os: ubuntu-lts-latest tools: - python: "3.10" + python: "3.12" apt_packages: - graphviz jobs: @@ -16,7 +17,14 @@ build: - playwright install chromium - python ./docs/scripts/generate_gallery_images.py +sphinx: + configuration: docs/conf.py + # builder: "dirhtml" + fail_on_warning: true + python: install: - method: pip - path: .[doc] + path: . + extra_requirements: + - doc From d357357a56382c1e58e6a76e29a5496b05c93669 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Wed, 18 Dec 2024 09:37:01 -0600 Subject: [PATCH 02/14] rename file --- readthedocs.yml => .readthedocs.yaml | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename readthedocs.yml => .readthedocs.yaml (100%) diff --git a/readthedocs.yml b/.readthedocs.yaml similarity index 100% rename from readthedocs.yml rename to .readthedocs.yaml From 813b30e990119436fd3bc238b3d24f9fbacbd8d0 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Thu, 16 Jan 2025 10:07:04 -0600 Subject: [PATCH 03/14] Update .readthedocs.yaml Co-authored-by: Tania Allard --- .readthedocs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 0beb32d8d..aac83def8 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -14,7 +14,7 @@ build: # build the gallery of themes before building the doc post_install: - pip install playwright - - playwright install chromium + - playwright install --with-deps chromium - python ./docs/scripts/generate_gallery_images.py sphinx: From 90a53225253fc788b62975cb03193a481cb4f718 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Thu, 16 Jan 2025 15:02:54 -0600 Subject: [PATCH 04/14] Update .readthedocs.yaml --- .readthedocs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index aac83def8..bc52577f6 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -14,7 +14,7 @@ build: # build the gallery of themes before building the doc post_install: - pip install playwright - - playwright install --with-deps chromium + - sudo playwright install --with-deps chromium - python ./docs/scripts/generate_gallery_images.py sphinx: From e11d83be7bf10e6187e3287187728468d3616fdd Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Thu, 16 Jan 2025 15:10:06 -0600 Subject: [PATCH 05/14] Revert "Update .readthedocs.yaml" This reverts commit 90a53225253fc788b62975cb03193a481cb4f718. --- .readthedocs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index bc52577f6..aac83def8 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -14,7 +14,7 @@ build: # build the gallery of themes before building the doc post_install: - pip install playwright - - sudo playwright install --with-deps chromium + - playwright install --with-deps chromium - python ./docs/scripts/generate_gallery_images.py sphinx: From 90496502f9c6cf17875245520f8e85af8105f4eb Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Tue, 21 Jan 2025 11:54:57 -0600 Subject: [PATCH 06/14] try installing deps with apt --- .readthedocs.yaml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index aac83def8..17e30bd88 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -8,13 +8,17 @@ build: os: ubuntu-lts-latest tools: python: "3.12" + # need to install playwright deps via apt (lack of sudo means we can't use + # `playwright install-deps`). NB: Graphviz is a separate dep urelated to playwright apt_packages: - graphviz + - libasound2 + - libdbus-glib-1-2 jobs: # build the gallery of themes before building the doc post_install: - pip install playwright - - playwright install --with-deps chromium + - playwright install chromium - python ./docs/scripts/generate_gallery_images.py sphinx: From 4396f95cfd4ffb74bd3aabafea23f7b7570771d3 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Tue, 21 Jan 2025 12:29:30 -0600 Subject: [PATCH 07/14] use nitpicky --- docs/conf.py | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index afab8132c..dcbb358bb 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -291,6 +291,17 @@ autoapi_root = "api" autoapi_member_order = "groupwise" +# -- Warnings / Nitpicky ------------------------------------------------------- + +nitpicky = True +nitpick_ignore_regex = [ + # we demo some `urllib` docs on our site; don't care that its xrefs fail to resolve + ( + r"py:.*", + r"autosummary: stub file not found 'urllib\.parse\..*'. Check your autosummary_generate setting\.", # noqa E501 + ), +] + # -- application setup ------------------------------------------------------- From 55389e4d6dec279509f40400df0032d94afb97c3 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Tue, 21 Jan 2025 12:41:50 -0600 Subject: [PATCH 08/14] minor cleanup --- tests/utils/check_warnings.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/utils/check_warnings.py b/tests/utils/check_warnings.py index f36a6172e..47813d011 100644 --- a/tests/utils/check_warnings.py +++ b/tests/utils/check_warnings.py @@ -30,8 +30,8 @@ def check_warnings(file: Path) -> bool: print("\n=== Sphinx Warnings test ===\n") # find the file where all the known warnings are stored - warning_file = Path(__file__).parent.parent / "warning_list.txt" - extra_warning_file = Path(__file__).parent.parent / "intermittent_warning_list.txt" + warning_file = Path(__file__).parents[1] / "warning_list.txt" + extra_warning_file = Path(__file__).parents[1] / "intermittent_warning_list.txt" received_warnings = escape_ansi(file.read_text()).strip().split("\n") expected_warnings = warning_file.read_text().strip().split("\n") From 071317be8da7755e2868a69e0c33f20a9eaaf02a Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Tue, 21 Jan 2025 12:44:10 -0600 Subject: [PATCH 09/14] remove the custom warnings checker --- tests/utils/check_warnings.py | 72 ----------------------------------- tox.ini | 6 +-- 2 files changed, 2 insertions(+), 76 deletions(-) delete mode 100644 tests/utils/check_warnings.py diff --git a/tests/utils/check_warnings.py b/tests/utils/check_warnings.py deleted file mode 100644 index 47813d011..000000000 --- a/tests/utils/check_warnings.py +++ /dev/null @@ -1,72 +0,0 @@ -"""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" - - 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)) diff --git a/tox.ini b/tox.ini index ac4f17675..99d090658 100644 --- a/tox.ini +++ b/tox.ini @@ -108,8 +108,7 @@ extras = {[testenv:docs-no-checks]extras} deps = py39-sphinx61-docs: sphinx~=6.1.0 commands = - sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs} - python tests/utils/check_warnings.py + sphinx-build -b html docs/ docs/_build/html -v {posargs} # recommended for local development, this command will build the PST documentation # with the default Sphinx version and the PST installed in editable mode @@ -122,8 +121,7 @@ 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 -w warnings.txt {posargs} - python tests/utils/check_warnings.py + sphinx-build -b html docs/ docs/_build/html -v {posargs} # 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 From b3addeba10b94e953a88db761ae027a3decc2d8d Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Tue, 21 Jan 2025 13:04:06 -0600 Subject: [PATCH 10/14] flesh out nitpicky ignores --- docs/conf.py | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index dcbb358bb..58f51c06a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -294,12 +294,36 @@ # -- Warnings / Nitpicky ------------------------------------------------------- nitpicky = True +dead_classes = ( + "api_sample.RandomNumberGenerator", + "b'abc def'", # urllib.parse.unquote_to_bytes + "bs4.BeautifulSoup", + "docutils.nodes.Node", + "matplotlib.artist.Artist", # matplotlib xrefs are in the class diagram demo + "matplotlib.figure.Figure", + "matplotlib.figure.FigureBase", + "pygments.formatters.HtmlFormatter", +) +# py:class reference target not found: b'abc def'. [ref.class] +nitpick_ignore = [ + ("py:class", f"reference target not found: {target} [ref.class]") + for target in dead_classes +] +urllib_pattern = r"urllib\.parse\.(Defrag|Parse|Split)Result(Bytes)?\.(count|index)" nitpick_ignore_regex = [ # we demo some `urllib` docs on our site; don't care that its xrefs fail to resolve + (r"py:obj", rf"reference target not found: {urllib_pattern} \[ref\.obj\]"), + ( + r"py:.*", + rf"autosummary: stub file not found '{urllib_pattern}'\. Check your " + r"autosummary_generate setting\.", + ), + # the kitchen sink pages include some intentional errors ( r"py:.*", - r"autosummary: stub file not found 'urllib\.parse\..*'. Check your autosummary_generate setting\.", # noqa E501 + r"'token' reference target not found: (suite|expression|target) \[ref\.token\]", ), + # ] # -- application setup ------------------------------------------------------- From ce874ecced111ddfa4fcfe16b1547bd962fdc4db Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Tue, 21 Jan 2025 14:01:52 -0600 Subject: [PATCH 11/14] Revert "remove the custom warnings checker" This reverts commit 071317be8da7755e2868a69e0c33f20a9eaaf02a. --- tests/utils/check_warnings.py | 72 +++++++++++++++++++++++++++++++++++ tox.ini | 6 ++- 2 files changed, 76 insertions(+), 2 deletions(-) create mode 100644 tests/utils/check_warnings.py diff --git a/tests/utils/check_warnings.py b/tests/utils/check_warnings.py new file mode 100644 index 000000000..47813d011 --- /dev/null +++ b/tests/utils/check_warnings.py @@ -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" + + 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)) diff --git a/tox.ini b/tox.ini index 99d090658..ac4f17675 100644 --- a/tox.ini +++ b/tox.ini @@ -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 From e5edd7da310ab0c0a4a3b139993fcaba13aaa7b1 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Tue, 21 Jan 2025 15:03:24 -0600 Subject: [PATCH 12/14] fixed nitpicky --- docs/conf.py | 38 ++++++++++++-------------------------- 1 file changed, 12 insertions(+), 26 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 58f51c06a..3c59d24fc 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -294,36 +294,22 @@ # -- Warnings / Nitpicky ------------------------------------------------------- nitpicky = True -dead_classes = ( - "api_sample.RandomNumberGenerator", - "b'abc def'", # urllib.parse.unquote_to_bytes - "bs4.BeautifulSoup", - "docutils.nodes.Node", - "matplotlib.artist.Artist", # matplotlib xrefs are in the class diagram demo - "matplotlib.figure.Figure", - "matplotlib.figure.FigureBase", - "pygments.formatters.HtmlFormatter", +bad_classes = ( + r".*abc def.*", # urllib.parse.unquote_to_bytes + r"api_sample\.RandomNumberGenerator", + r"bs4\.BeautifulSoup", + r"docutils\.nodes\.Node", + r"matplotlib\.artist\.Artist", # matplotlib xrefs are in the class diagram demo + r"matplotlib\.figure\.Figure", + r"matplotlib\.figure\.FigureBase", + r"pygments\.formatters\.HtmlFormatter", ) -# py:class reference target not found: b'abc def'. [ref.class] -nitpick_ignore = [ - ("py:class", f"reference target not found: {target} [ref.class]") - for target in dead_classes -] -urllib_pattern = r"urllib\.parse\.(Defrag|Parse|Split)Result(Bytes)?\.(count|index)" nitpick_ignore_regex = [ + *[("py:class", target) for target in bad_classes], # we demo some `urllib` docs on our site; don't care that its xrefs fail to resolve - (r"py:obj", rf"reference target not found: {urllib_pattern} \[ref\.obj\]"), - ( - r"py:.*", - rf"autosummary: stub file not found '{urllib_pattern}'\. Check your " - r"autosummary_generate setting\.", - ), + ("py:obj", r"urllib\.parse\.(Defrag|Parse|Split)Result(Bytes)?\.(count|index)"), # the kitchen sink pages include some intentional errors - ( - r"py:.*", - r"'token' reference target not found: (suite|expression|target) \[ref\.token\]", - ), - # + ("token", r"(suite|expression|target)"), ] # -- application setup ------------------------------------------------------- From e24a7350abac81176dba1201d47d7ed4b9bdc0a2 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Tue, 21 Jan 2025 15:21:36 -0600 Subject: [PATCH 13/14] don't fail RTD on warning --- .readthedocs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 17e30bd88..221ca4396 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -24,7 +24,7 @@ build: sphinx: configuration: docs/conf.py # builder: "dirhtml" - fail_on_warning: true + fail_on_warning: false # we have some unavoidable warnings, and a separate warnings checker python: install: From 8e6d749861e36021bff0a82ece66c222da26f92e Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Tue, 21 Jan 2025 15:22:12 -0600 Subject: [PATCH 14/14] toxfile: build w/ nitpicky; show full traceback on fail --- tox.ini | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tox.ini b/tox.ini index ac4f17675..5bfa951ba 100644 --- a/tox.ini +++ b/tox.ini @@ -108,7 +108,7 @@ extras = {[testenv:docs-no-checks]extras} deps = py39-sphinx61-docs: sphinx~=6.1.0 commands = - sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs} + sphinx-build -b html docs/ docs/_build/html -nTv -w warnings.txt {posargs} python tests/utils/check_warnings.py # recommended for local development, this command will build the PST documentation @@ -122,7 +122,7 @@ 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 -w warnings.txt {posargs} + sphinx-build -b html docs/ docs/_build/html -nTv -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