[doc] Remove/update some old Sphinx hacks - #24930
Conversation
tyler-yankee
added
the
release notes: none
|
@drake-jenkins-bot linux-noble-unprovisioned-gcc-bazel-experimental-documentation please. |
0418456 to
f2028d2
Compare
tyler-yankee
left a comment
tyler-yankee
left a comment
There was a problem hiding this comment.
+a:@mwoehlke-kitware for feature review, please.
@tyler-yankee reviewed 1 file and all commit messages, and made 1 comment.
Reviewable status: LGTM missing from assignee mwoehlke-kitware, needs platform reviewer assigned, needs at least two assigned reviewers (waiting on mwoehlke-kitware).
mwoehlke-kitware
left a comment
mwoehlke-kitware
left a comment
There was a problem hiding this comment.
@mwoehlke-kitware made 1 comment.
Reviewable status: needs platform reviewer assigned, needs at least two assigned reviewers.
tyler-yankee
left a comment
tyler-yankee
left a comment
There was a problem hiding this comment.
I'm a bit concerned that sort_members is in a module called _legacy_class_based as of latest Sphinx (9.1.0), but in 7.2.6 it's not spelled that way, so I think it's fine for now. We'll have to cross that bridge in the future during an upgrade, but IMO this PR is already doing enough. The main goal here is to remove as much old cruft as possible so that the surface area to paw through (and potential failure modes) when fixing the docs for nanobind is less.
I did my best to sanity check the generated documentation locally, but there are probably some edge cases I'm missing where I'll lean on more pydrake-knowledgeable TRI folks. Speaking of which, +a:@rpoyner-tri, would you like to review this one?
@tyler-yankee made 1 comment.
Reviewable status: LGTM missing from assignee rpoyner-tri(platform) (waiting on mwoehlke-kitware and rpoyner-tri).
tyler-yankee
left a comment
tyler-yankee
left a comment
There was a problem hiding this comment.
@tyler-yankee made 1 comment.
Reviewable status: 1 unresolved discussion, LGTM missing from assignee rpoyner-tri(platform) (waiting on mwoehlke-kitware, rpoyner-tri, and tyler-yankee).
a discussion (no related file):
working
The new "pybind11_object bases removal" code has the following visual effect:
before:
after:
This seems like an ugly artifact, so I'll look into restoring
f2028d2 to
7662243
Compare
Our minimum-supported Sphinx version is currently 7.2.6, but most of this extension code was written under much older versions (1.* or 2.*). We can take better advantage of many new upstream features. * Instead of fully vendoring `add_directive_header`, hook into the `autodoc-process-bases` event provided in Sphinx 5.1. * Instead of fully vendoring `document_members`, target the narrower `sort_members` helper which has since been factored out upstream. * Drop branches that were conditional on older versions of Sphinx than our minimum supported.
tyler-yankee
left a comment
tyler-yankee
left a comment
There was a problem hiding this comment.
@tyler-yankee reviewed 1 file and all commit messages, made 1 comment, and resolved 1 discussion.
Reviewable status: LGTM missing from assignee rpoyner-tri(platform) (waiting on mwoehlke-kitware and rpoyner-tri).
a discussion (no related file):
Previously, tyler-yankee (Tyler Yankee) wrote…
working
The new "pybind11_object bases removal" code has the following visual effect:
before:
after:
This seems like an ugly artifact, so I'll look into restoring
done
mwoehlke-kitware
left a comment
mwoehlke-kitware
left a comment
There was a problem hiding this comment.
@mwoehlke-kitware reviewed 1 file and all commit messages.
Reviewable status: LGTM missing from assignee rpoyner-tri(platform) (waiting on rpoyner-tri).
3 participants
Our minimum-supported Sphinx version is currently 7.2.6, but most of this extension code was written under much older versions (1.* or 2.*). We can take better advantage of many new upstream features.
add_directive_header, hook into theautodoc-process-basesevent provided in Sphinx 5.1 (https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#event-autodoc-process-bases).document_members, target the narrowersort_membershelper which has since been factored out upstream (https://github.com/sphinx-doc/sphinx/blob/e44a40eb2f810558ccd9da1425421270ccb81351/sphinx/ext/autodoc/_legacy_class_based/_documenters.py#L1066).Towards #24895.
This change is