DOC: Suppress distutils doc build warnings for python 3.12+ #29160
Conversation
Enables an error free build of the docs for python 3.12+. Excludes related files, supresses all warnings for excluded files, and ignores case-by-case individual references. Closes numpy#29131. [skip azp][skip cirrus][skip actions]
| suppress_warnings += [ | ||
| 'toc.excluded', # Suppress warnings about excluded toctree entries | ||
| ] |
There was a problem hiding this comment.
This bit is my only concern, as it suppresses ALL toc.excluded warnings. The Sphinx documentation related to this warning is a bit sparse, so I'm not sure how greedy this suppression will be. If it only suppresses the files explicitly listed above (the two we want excluded), then I'm happy with this fix.
I've tried using the only and ifconfig directives to deal conditional toctree inclusions, but that route will fail because the toctree is read before any conditional statements are applied.
There was a problem hiding this comment.
Tracing the code relate to toc.excluded, I inclined to think the global suppression of toc.excluded will be safe (only suppress warnings to thing that have manually been excluded already).
On another note, should we worry about the "/" in "reference/distutils.rst" and "reference/distutils/misc_util.rst"? This seems like it could cause Windows doc build issues. I just followed the existing "reference/distutils.rst" when adding another line, but now I'm concerned it will cause windows doc builds to fail. I don't have a working Windows environment to test a doc build on. Thoughts?
There was a problem hiding this comment.
When is the np.distutils removal going to happen? I think this is fine as a temporary solution until then.
|
The tests do not cover testing a new codespaces doc build. I tested buliding the docs using this branch on a new codespaces as well as a virtual machine (in windows 11) running Ubuntu 24.04 after creating a fresh conda environment from |
Enables an error free build of the docs for python 3.12+. Excludes related files, supresses all warnings for excluded files, and ignores case-by-case individual references. Closes #29131.
[skip azp][skip cirrus][skip actions]