Commit 4e88c8f
[doc][DOC-898] probe: remove MockedClassDocumenter monkey-patch in conf.py (ray-project#63197)
## Why
The Anyscale docs team is auditing `doc/source/conf.py` against current
Ray state as part of strategy work tracked in
[anyscale/docs#2064](https://github.com/anyscale/docs/pull/2064). One
finding: `conf.py` globally swaps `sphinx.ext.autodoc.ClassDocumenter`
with a `MockedClassDocumenter` subclass that suppresses the `Bases:
object` line for classes that inherit directly from `object`.
The patch was added in
[ray-project#39982](ray-project#39982) (Oct 2023). It's
a cosmetic workaround. Two reasons it may now be obsolete:
1. **Modern pydata-sphinx-theme** (Ray pins 0.14.1; current is 0.16.x)
renders base class lines differently than it did when the patch was
authored.
2. **Global monkey patches at conf.py module scope** are a fragility
liability — if a future Sphinx ClassDocumenter signature change lands,
the patch breaks the build at import. The cosmetic value should be
weighed against that ongoing maintenance cost.
## What this PR does
1. Removes the `MockedClassDocumenter` class and its global assignment
to `sphinx.ext.autodoc.ClassDocumenter`.
2. Removes the now-unused `from sphinx.ext import autodoc` import.
## How to validate
This is a probe, not a request-for-merge. The validation surfaces are:
1. **RtD PR preview build** — runs against this branch. With
`fail_on_warning: true` set in `.readthedocs.yaml`, any new Sphinx
warning means the patch was still load-bearing in a non-cosmetic way.
2. **`doc: check API doc consistency`** — premerge step that runs `make
-C doc/ html` internally. Same fail-on-warning gate.
3. **Visual diff of any API ref page** for a class that inherits
directly from `object`. If `Bases: object` reappears in those pages, the
patch was effectively suppressing visible noise — keep it. If the line
is rendered the same way (or absent) by the modern theme without the
patch, drop it.
## Possible outcomes
- **Build clean, no visible regression** → the patch is dead weight.
Drop.
- **Build clean, `Bases: object` reappears on many pages** → the patch
is doing what it claims. Keep, and add a comment explaining what would
replace it (a CSS rule on the modern theme's rendered output, or a
different autodoc filter).
- **Build fails** → the patch was load-bearing in a way nobody
documented. Revert and document.
## Status
**Draft.** Posting for visibility and validation, not for merge. Looking
for a Ray maintainer to confirm whether the cosmetic suppression is
still desired and whether there's a less-fragile mechanism to achieve
it. Justin Yu @justinvyu, Aydin Abiar @aslonnie, or Elliot Barnwell
@ebarn-anyscale would all be reasonable reviewers given recent activity
in this area.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Signed-off-by: Douglas Strodtman <douglas@anyscale.com>1 parent c48711d commit 4e88c8f
1 file changed
Lines changed: 0 additions & 12 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
15 | 15 | | |
16 | 16 | | |
17 | 17 | | |
18 | | - | |
19 | 18 | | |
20 | 19 | | |
21 | 20 | | |
| |||
858 | 857 | | |
859 | 858 | | |
860 | 859 | | |
861 | | - | |
862 | | - | |
863 | | - | |
864 | | - | |
865 | | - | |
866 | | - | |
867 | | - | |
868 | | - | |
869 | | - | |
870 | | - | |
871 | | - | |
872 | 860 | | |
873 | 861 | | |
874 | 862 | | |
| |||
0 commit comments