update ReadTheDocs settings file #2083

drammock · 2024-12-18T15:38:11Z

ReadTheDocs is making some changes that affect us. Will leave self-review to explain the changes.

drammock

note also the filename changed from readthedocs.yml to .readthedocs.yaml, as the RTD interface says that this is the only allowed filename (?! makes me wonder if our existing settings file is even being read?)

drammock · 2024-12-18T15:38:28Z

.readthedocs.yaml

 formats:
  - htmlzip

 # build with latest available ubuntu version
 build:
-  os: ubuntu-20.04
+  os: ubuntu-lts-latest


this just seems like common sense

drammock · 2024-12-18T15:38:42Z

.readthedocs.yaml

  tools:
-    python: "3.10"
+    python: "3.12"


ditto, no reason to build on an old Py version

drammock · 2024-12-18T15:39:17Z

.readthedocs.yaml

+sphinx:
+  configuration: docs/conf.py


this bit is now required, and our builds will start failing in January without it.

drammock · 2024-12-18T15:39:46Z

.readthedocs.yaml

+      path: .
+      extra_requirements:
+        - doc


this is the recommended way to do what we were doing before with path: .[doc]

drammock · 2024-12-18T15:42:05Z

.readthedocs.yaml

+sphinx:
+  configuration: docs/conf.py
+  # builder: "dirhtml"
+  fail_on_warning: true


this is good practice but will probably not work for us, given the long list of "expected" warnings that our build produces. 🤔 maybe we should revisit how we handle that, e.g., using a nitpick_ignore in conf.py instead of writing warnings to file and using a post-build script to check them against our "expected warnings" lists. Let's see what happens.

github-actions · 2024-12-18T15:48:03Z

Coverage report

This PR does not seem to contain any modification to coverable code.

drammock · 2024-12-18T15:56:02Z

hmm, hitting

║ Host system is missing dependencies to run browsers. ║
║ Please install them with the following command:      ║
║                                                      ║
║     sudo playwright install-deps

which wasn't happening before, e.g. on recent build https://readthedocs.org/projects/pydata-sphinx-theme/builds/26618254/

I wonder if it's due to the Ubuntu version bump? Will investigate.

.readthedocs.yaml

Co-authored-by: Tania Allard <taniar.allard@gmail.com>

.readthedocs.yaml

drammock · 2025-01-16T21:09:12Z

.readthedocs.yaml

  apt_packages:
    - graphviz
  jobs:
    # build the gallery of themes before building the doc
    post_install:
      - pip install playwright
-      - playwright install chromium
+      - sudo playwright install --with-deps chromium


argh, without sudo we get a password error:

Switching to root user to install dependencies... Password: su: Authentication failure Failed to install browsers

but with sudo it fails as

/bin/sh: 1: sudo: not found

searching RTD docs for "sudo" is a dead end. Anyone with more RTD config experience want to help me out here?

I remember using playwright some time ago in Read the Docs and I installed the dependencies using build.apt_packages and without using --with-deps in this command.

Example:

version: 2 # ... other configs build: apt_packages: - libasound2 - libdbus-glib-1-2 jobs: post_install: - pip install playwright - playwright install chromium

It may require a small change, but this is what I remember. If that works for you, we should probably document this approach. Let me know if it works.

thanks for the suggestion. Unfortunately I don't know what to add to apt_packages because playwright doesn't actually tell us which dependencies are missing:

║ Host system is missing dependencies to run browsers. ║ ║ Please install them with the following command: ║ ║ ║ ║ sudo playwright install-deps

(#2083 (comment))

That error wasn't happening prior to this PR so might be a result of the ubuntu version bump (?) but regardless, playwright's install-deps subcommand is expressly meant for CI usage so it seems a shame to reverse-engineer it here. Is there no way to get sudo on a post_install job?

I don't know what to add to apt_packages because playwright

Have you tried using the dependencies I put in my example?

it seems a shame to reverse-engineer it here

It's not reverse-engineer, it's installing the dependencies required by playwright in an environment without sudo capabilities.

Is there no way to get sudo on a post_install job?

No, sudo is not available on Read the Docs builders.

ah, sorry! I misunderstood, I didn't realize libasound and libdbus were the actual playwright dependencies (thought it was a generic example demoing apt_packages). I will try that.

that fixed it! Thanks @humitos and sorry for the misunderstanding before.

This reverts commit 90a5322.

drammock · 2025-01-21T15:49:29Z

@humitos we've started hitting the rolling doc build fails, and haven't yet managed to get the config changes to work for us. In particular we can't seem to get playwright to install correctly anymore: #2083 (comment)
Any chance you know what we're doing wrong there?

This reverts commit 071317b.

drammock

@trallard CIs are all green here, this is ready for another look.

drammock · 2025-01-21T21:29:57Z

docs/conf.py

+nitpicky = True
+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",
+)
+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
+    ("py:obj", r"urllib\.parse\.(Defrag|Parse|Split)Result(Bytes)?\.(count|index)"),
+    # the kitchen sink pages include some intentional errors
+    ("token", r"(suite|expression|target)"),
+]


This captures all of the unavoidable "reference target not found" warnings that sphinx generates when nitpicky is turned on. Now, if a new bad cross-ref gets introduced, it will show up as a warning, and cause our post-build warnings checker function to fail.

(even with this, there are still ~15 warnings that are always generated, but they're not sphinx xref errors, so can't be dealt with by the nitpicky system. cf. tests/warning_list.txt)

drammock · 2025-01-21T21:30:28Z

tests/utils/check_warnings.py

+    warning_file = Path(__file__).parents[1] / "warning_list.txt"
+    extra_warning_file = Path(__file__).parents[1] / "intermittent_warning_list.txt"


unrelated simplification, noticed in passing

drammock · 2025-01-21T21:31:13Z

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}


-n forces nitpicky mode. Not strictly necessary, since we set nitpicky=True in conf.py now

-T show full traceback on error.

drammock added 2 commits December 18, 2024 09:35

update RTD config

c1130c5

rename file

d357357

drammock commented Dec 18, 2024

View reviewed changes

trallard reviewed Jan 16, 2025

View reviewed changes

.readthedocs.yaml Show resolved Hide resolved

Update .readthedocs.yaml

813b30e

Co-authored-by: Tania Allard <taniar.allard@gmail.com>

drammock commented Jan 16, 2025

View reviewed changes

.readthedocs.yaml Outdated Show resolved Hide resolved

Update .readthedocs.yaml

90a5322

drammock commented Jan 16, 2025

View reviewed changes

Revert "Update .readthedocs.yaml"

e11d83b

This reverts commit 90a5322.

drammock mentioned this pull request Jan 21, 2025

Read the Docs build fails #2101

Open

drammock added 9 commits January 21, 2025 11:54

try installing deps with apt

9049650

use nitpicky

4396f95

minor cleanup

55389e4

remove the custom warnings checker

071317b

flesh out nitpicky ignores

b3addeb

Revert "remove the custom warnings checker"

ce874ec

This reverts commit 071317b.

fixed nitpicky

e5edd7d

don't fail RTD on warning

e24a735

toxfile: build w/ nitpicky; show full traceback on fail

8e6d749

drammock commented Jan 21, 2025

View reviewed changes

This was referenced Jan 21, 2025

Add support for versionremoved directive #2087

Open

BUG - center search dialog on wide screens #2085

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

update ReadTheDocs settings file #2083

update ReadTheDocs settings file #2083

drammock commented Dec 18, 2024 •

edited

Loading

drammock left a comment

drammock Dec 18, 2024

drammock Dec 18, 2024

drammock Dec 18, 2024

drammock Dec 18, 2024

drammock Dec 18, 2024

github-actions bot commented Dec 18, 2024

drammock commented Dec 18, 2024

drammock Jan 16, 2025 •

edited

Loading

humitos Jan 21, 2025

drammock Jan 21, 2025 •

edited

Loading

humitos Jan 21, 2025

drammock Jan 21, 2025

drammock Jan 21, 2025

drammock commented Jan 21, 2025

drammock left a comment

drammock Jan 21, 2025

drammock Jan 21, 2025

drammock Jan 21, 2025

		warning_file = Path(__file__).parents[1] / "warning_list.txt"
		extra_warning_file = Path(__file__).parents[1] / "intermittent_warning_list.txt"

update ReadTheDocs settings file #2083

Are you sure you want to change the base?

update ReadTheDocs settings file #2083

Conversation

drammock commented Dec 18, 2024 • edited Loading

drammock left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Dec 18, 2024

Coverage report

drammock commented Dec 18, 2024

drammock Jan 16, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

drammock Jan 21, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

drammock commented Jan 21, 2025

drammock left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

drammock commented Dec 18, 2024 •

edited

Loading

drammock Jan 16, 2025 •

edited

Loading

drammock Jan 21, 2025 •

edited

Loading