readthedocs broken

[henryiii]

Describe the bug

The docs are broken, the "stable" release did not build after the recent release (missing from changelog), with:

AttributeError: 'HTMLParser' object has no attribute 'unescape'

See https://readthedocs.org/projects/nox/builds/

This should be fixable by setting a minimum version on some of the docs dependencies (why are those mixed with the test dependencies?) - readthedocs installs old versions of things by default, and then it's a no-op if you don't force an upgrade. Why they install a version of (something that uses HTML) that doesn't support Python 3.9+, I'm not sure, but forcing sphinx>=4 or something like that will likely fix the problem. Downgrading to Python 3.8 for the docs would fix it, too, but that's the wrong way to initially try to fix it.

I would highly recommend enabling PR readthedocs builds (in the readthedocs settings), they are very handy for catching bugs in the docs builds.

Also, it looks like "latest" hasn't built in a year or more, I'm guessing it was never changed to main from master, perhaps? It makes "latest" much older than "stable".

[henryiii]

PS: I think @dhermes or @theacodes is required for adding PR builds & changing the "latest" target branch.

[dhermes]

I can confirm I have admin on the RTD project.

[henryiii]

I checked, readthedocs runs pip install ... sphinx<2 ... before installing any project. Sphinx<2 does not support Python 3.9. Have I mentioned I hate version capping? At least it's not an actual requirement. I knew they did that, but even on Python 3.9+, that I was not expecting. Fixing it should be as simple as adding sphinx>=2 (or 3 or 4) in the requirements, which will cause the pre-installed sphinx to be upgraded.

[dhermes]

So far I have explicitly set the default branch to main in https://readthedocs.org/dashboard/nox/advanced/ and kicked off a latest build (https://readthedocs.org/projects/nox/builds/15742724/) to ensure it pulls main

[henryiii]

If you want to activate PR readthedocs builds I can make a PR with that fix.

[dhermes]

Will do (though I'm going to turn it off after it's fixed, it's a big use of resources for not much return IMO).

IMO we should also check in a .readthedocs.yml

DERP I missed https://github.com/theacodes/nox/blob/386659e446aacdd681b5e1f25db6a2c03180a287/.readthedocs.yml

[dhermes]

PR builds are now enabled

UPDATE 3:39pm Central: I have disabled this again

[henryiii]

There is one, that's what's setting 3.10. I find PR builds quite helpful, as you can preview the changes to the docs, and it also avoids broken documentation builds (which tend to be be very quiet), and in this case, it takes 32 seconds. But up to you. I'm making the PR.

[henryiii]

I see there is a GHA docs build, but you can't preview it, and it doesn't do the 'pre-install' that readthedocs tends to break things with.

[dhermes]

#560 didn't fix it, re-opening

"Running Sphinx v4.3.2" https://readthedocs.org/projects/nox/builds/15742871/ still fails

html.parser.HTMLParser().unescape was removed in Python 3.9 IIUC

[cjolowicz]

The stable docs on RTD still point to an old release (2021.10.1) instead of the latest release, 2022.1.7. The cause for the broken docs build has been fixed on main, but we need to rebuild stable on RTD.

The thread at #561 (comment) discussed two methods to fix this:

• Push a tag 2022.1.7.post1 to GitHub; or
• Push a stable branch and configure the RTD project to track this branch for stable docs.

Personally, I'd prefer the first method as it seems less overhead and well within the purpose of post releases. I don't think there's a need to do anything beyond pushing the git tag. The second approach offers flexibility and avoids a release, but it also means we'll need to either maintain the stable branch in the future, or rollback the RTD config after the rebuild.

@theacodes Would you be happy with this approach?

[DiddiLeija]

I'm also +1 with pushing a 2022.1.7.post1 tag, since we have only changed docs and deps, so creating a post release will be ok.

[henryiii]

There's a third method: just point rtd stable at main, click rebuild, then put it back to releases only.

[cjolowicz]

Also good :)

[cjolowicz]

@theacodes @dhermes friendly bump

[cjolowicz]

Hello all,

Heads up: I'll push the 2022.1.7.post1 tag tomorrow to fix the problem with our docs being outdated.

Please give a shout if you have any objections. I don't have access to Read the Docs, so this is the only viable option right now to get our docs up-to-date.

cc @theacodes @dhermes

OT: pip 22.0 (2022-01-29) officially switched to Nox for automation 🎉

[DiddiLeija]

OT: pip 22.0 (2022-01-29) officially switched to Nox for automation 🎉

🥳 pypa/pip#10693

[dhermes]

@cjolowicz Let me just add you to the RTD project.

---

Update: done; I added https://readthedocs.org/profiles/cjolowicz/

[cjolowicz]

Awesome, thank you @dhermes !

In this case I'll go for the option proposed by @henryiii above, to avoid the extra PyPI release.

[cjolowicz]

Unless I'm missing something, you can't actually point stable to the main branch.¹

So back to the original plan: Pushing a 2022.1.7.post1 tag tomorrow.

Drop a comment if you have a better idea. Alternatives I've considered:

• Pushing a branch for the version instead of a tag (too hacky?)
• Pushing a stable branch (overhead of maintaining an extra long-lived branch)
• Pushing a stable branch, then removing it after the docs build (too hacky?)

Footnotes

1. See https://docs.readthedocs.io/en/stable/versions.html. They do support a branch named stable, as well as any branch with a name following semantic versioning. ↩

[dhermes]

You can push a tag without doing a PyPI release?

[cjolowicz]

You can push a tag without doing a PyPI release?

Our CI publishes to PyPI when a tag is pushed:

https://github.com/theacodes/nox/blob/17a6a15c0ea1cc056140f5d37a467477ce05f5a5/.github/workflows/ci.yml#L61-L69

[FollowTheProcess]

@cjolowicz +1 for the post1 release from me

[henryiii]

Make sure it doesn’t include #526 ;)

[cjolowicz]

Stable docs are up-to-date now.

2022.1.7.post1 only includes the two docs fixes that came after 2022.1.7.

Interestingly, the PyPI release did not happen. The version number in setup.cfg did not change, so while the tag triggered the deploy job in CI, PyPI rejected the upload with "File already exists". Which is just as well :)

[henryiii]

Haha, nice. :)