support for Sphinx v8.0

[2bndy5]

using the 8.0.2 from pypi

Thanks to awareness in sphinx-doc/sphinx#12629

[2bndy5]

I suppose we could add the git master branch of sphinx to our CI. But that might be over-zealous given our sporadic maintainence.

Note

Dependabot does not support notifying us of pre-releases (that I'm aware of).

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 67.19%. Comparing base (6118569) to head (04e1ff2).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #376   +/-   ##
=======================================
  Coverage   67.19%   67.19%           
=======================================
  Files          68       68           
  Lines        8515     8515           
=======================================
  Hits         5722     5722           
  Misses       2793     2793           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[jbms]

I suppose we could add the git master branch of sphinx to our CI. But that might be over-zealous given our sporadic maintainence.

Note

Dependabot does not support notifying us of pre-releases (that I'm aware of).

Could be a good idea.

[2bndy5]

I'm ok with leaving this PR open until Sphinx v8 stable is released. If there are other pre-releases that need additional compliance, then I'll add it to this branch.

[2bndy5]

I've seen the master branch used in CI on the breathe project. It really just strained the sparse development efforts to maintain support for Sphinx' bleeding edge. We have enough monkey patching to worry about in Sphinx stable channel.

[jbms]

Now that sphinx 8 is released it is probably time to submit this.

[2bndy5]

First, I should probably add sphinx v8 to CI tests job.

[jbms]

Yeah. The number of combinations is getting quite high. Potentially we should run more than one sphinx version per job to save on setup cost.

[2bndy5]

Are you thinking the CI matrix for tests should only iterate over python version and node version and OS?

[2bndy5]

I think I could configure nox to skip certain sphinx versions if testing an unsupported python version.

[2bndy5]

Ok I reduced the number of CI jobs by running tests per OS, python version and node.js version.

I also incorporated some GitHub workflow commands to group logs from certain nox sessions.

This should make it easier to read the CI logs when we need to find what went wrong in a certain nox session.

Note

There may be some discrepancies about which log() outputs (beginning and/or ending statements) are grouped because logger handlers acquire a stdout lock. Using nox.session.log() won't group the logs because GitHub expects the grouping commands to have nothing prefixed (the prefix nox > will negate log grouping). I tried to preempt this by using a separate Logger instance (that doesn't propagate to root handlers), but it doesn't seem to be consistent, although it is better than using print(..., flush=True).

It would be greatly beneficial (in CI runtime) to be able to cache the graphviz installation, but the amount of dependencies for that app make it near impossible to sustain.