Fix all Sphinx reference warnings in the documentation #101100
Comments
|
See also: https://discuss.python.org/t/broken-references-in-sphinx-docs/19463 IMO, we should fix these. Many are actual issues in the documentation. Here's a proof-of-concept GH Action that complains about nitpicks in changed files only: encukou@e97d91f |
Yes, definitely; I've been gradually helping on the docs I've/we've touched anyway, though it is a long term project. I've found a number of things that were undocumented, as well as a number of other real issues through that, e.g. on the
I'd argue neither is exactly innocent:
There's a third, much simpler and better fix. If the link isn't desired, every Sphinx cross-reference role supports prepending
|
|
I've sent an example PR with the fix for The dev experience was plesant, because on the second run
|
|
As a general note of caution, especially when submitting PRs fixing these sorts of widespread and potentially nitpicky (heh) docs defects, especially when in cases like this there are a number of different possibilities to handle each warning instance, we should take care to avoid the folly of large "omnibus" PRs (as Guido likes to call them) and take care to consider each specific change we're making holistically, and ensure that we're picking the approach that best serves the reader in for each specific context, as opposed to just applying one type of fix mechanically to all instances, or even worse arbitrarily picking one or another each time without careful thought and consideration that might fix the warning but be an overall regression. Otherwise, if we're too focused solely on the narrow objective of getting rid of the warnings by whatever means, as opposed to the broader goal of improving the overall quality of the docs, we risk both doing exactly the opposite of the latter, and consuming the limited time and churn budget of core developers and other reviewers on changes with little or even negative practical benefit. |
|
That's the reasoning behind teaching the CI to only warn, and only on changed files. |
* gh-101100: [Enum] Fix sphinx warnings in Co-authored-by: C.A.M. Gerlach <[email protected]>
* pythongh-101100: [Enum] Fix sphinx warnings in (cherry picked from commit 9e025d3) Co-authored-by: Nikita Sobolev <[email protected]> Co-authored-by: C.A.M. Gerlach <[email protected]>
…1173) (cherry picked from commit 9e025d3) Co-authored-by: Nikita Sobolev <[email protected]> Co-authored-by: C.A.M. Gerlach <[email protected]>
|
To enable this, it would be really useful if Sphinx had more granular config for the warnings/errors, similar to Flake8. For example, we could enable nitpicky only for certain directories and files, and expand as more are cleaned. And possibly in combination with an exclude option. Similarly, we may only want to enable/disable nitpicky for certain classes of warnings/errors. That would allow us to iteratively fix things, and keep them fixed. cc @AA-Turner |
|
PR to fix 113 warnings in the |
|
Yeah; you can silence warnings for particular names, but not in particular files, which would IMO be much more useful. Besides just incrementally fixing these issues, it would also be very useful to potentially keep permanently for What's New and Changelog pages (other than those for the current feature version in a particular branch) as those will naturally drift out of date over time. I believe I mentioned this on a Sphinx issue somewhere at some point semi-recently, but if I did I can't seem to find it now. |
|
Does anybody have an opinion on the docstring-side of matters? In other words, should the docstrings inside the Python source code also comply to Sphinx's nit-picky mode? (see e.g. #100989) |
|
IMO, it's generally helpful for the docstrings to use the unambiguous, explicit and precise types if feasible, but particularly for the docstrings, avoiding warnings in In the particular case of your PR #100990 , it appears to make substantial clarity and descriptiveness improvements to the docstrings beyond just the above change (which is really secondary in benefit to the latter), so to me it appears to be a pretty clear net win. |
Co-authored-by: C.A.M. Gerlach <[email protected]>
…2125) (cherry picked from commit b7c1126) Co-authored-by: Hugo van Kemenade <[email protected]> Co-authored-by: C.A.M. Gerlach <[email protected]>
…2125) (cherry picked from commit b7c1126) Co-authored-by: Hugo van Kemenade <[email protected]> Co-authored-by: C.A.M. Gerlach <[email protected]>
(cherry picked from commit b7c1126) Co-authored-by: Hugo van Kemenade <[email protected]> Co-authored-by: C.A.M. Gerlach <[email protected]>
(cherry picked from commit b7c1126) Co-authored-by: Hugo van Kemenade <[email protected]> Co-authored-by: C.A.M. Gerlach <[email protected]>
…m classes" section of the data model docs (python#124480)
* main: (69 commits) Add "annotate" SET_FUNCTION_ATTRIBUTE bit to dis. (python#124566) pythongh-124412: Add helpers for converting annotations to source format (python#124551) pythongh-119180: Disallow instantiation of ConstEvaluator objects (python#124561) For-else deserves its own section in the tutorial (python#123946) Add 3.13 as a version option to the crash issue template (python#124560) pythongh-123242: Note that type.__annotations__ may not exist (python#124557) pythongh-119180: Make FORWARDREF format look at __annotations__ first (python#124479) pythonGH-58058: Add quick reference for `ArgumentParser` to argparse docs (pythongh-124227) pythongh-41431: Add `datetime.time.strptime()` and `datetime.date.strptime()` (python#120752) pythongh-102450: Add ISO-8601 alternative for midnight to `fromisoformat()` calls. (python#105856) pythongh-124370: Add "howto" for free-threaded Python (python#124371) pythongh-121277: Allow `.. versionadded:: next` in docs (pythonGH-121278) pythongh-119400: make_ssl_certs: update reference test data automatically, pass in expiration dates as parameters python#119400 (pythonGH-119401) pythongh-119180: Avoid going through AST and eval() when possible in annotationlib (python#124337) pythongh-124448: Update Windows builds to use Tcl/Tk 8.6.15 (pythonGH-124449) pythongh-123884 Tee of tee was not producing n independent iterators (pythongh-124490) pythongh-124378: Update test_ttk for Tcl/Tk 8.6.15 (pythonGH-124542) pythongh-124513: Check args in framelocalsproxy_new() (python#124515) pythongh-101100: Add a table of class attributes to the "Custom classes" section of the data model docs (python#124480) Doc: Use ``major.minor`` for documentation distribution archive filenames (python#124489) ...
Using a standard library class makes this test difficult to maintain as other tests and other parts of the stdlib may create subclasses, which may still be alive when this test runs depending on GC timing.
Using a standard library class makes this test difficult to maintain as other tests and other parts of the stdlib may create subclasses, which may still be alive when this test runs depending on GC timing.
Using a standard library class makes this test difficult to maintain as other tests and other parts of the stdlib may create subclasses, which may still be alive when this test runs depending on GC timing. (cherry picked from commit 08a467b) Co-authored-by: Jelle Zijlstra <[email protected]>
…124577) Using a standard library class makes this test difficult to maintain as other tests and other parts of the stdlib may create subclasses, which may still be alive when this test runs depending on GC timing. (cherry picked from commit 08a467b) Co-authored-by: Jelle Zijlstra <[email protected]>
…4579) gh-101100: Make __subclasses__ doctest stable (GH-124577) Using a standard library class makes this test difficult to maintain as other tests and other parts of the stdlib may create subclasses, which may still be alive when this test runs depending on GC timing. (cherry picked from commit 08a467b) Co-authored-by: Jelle Zijlstra <[email protected]>
) Co-authored-by: Hugo van Kemenade <[email protected]> Co-authored-by: Barry Warsaw <[email protected]> Co-authored-by: Jelle Zijlstra <[email protected]>
…ythonGH-124106) (cherry picked from commit a5716a3) Co-authored-by: Hugo van Kemenade <[email protected]>
…ythonGH-124106) (cherry picked from commit a5716a3) Co-authored-by: Hugo van Kemenade <[email protected]>
…H-124106) (#125190) Co-authored-by: Hugo van Kemenade <[email protected]>
…H-124106) (#125191) Co-authored-by: Hugo van Kemenade <[email protected]>
…tributes (python#124709) Co-authored-by: Hugo van Kemenade <[email protected]> Co-authored-by: Barry Warsaw <[email protected]> Co-authored-by: Jelle Zijlstra <[email protected]>
#124709) (#125208) Co-authored-by: Hugo van Kemenade <[email protected]> Co-authored-by: Barry Warsaw <[email protected]> Co-authored-by: Jelle Zijlstra <[email protected]>
…ributes (python#124709) Co-authored-by: Hugo van Kemenade <[email protected]> Co-authored-by: Barry Warsaw <[email protected]> Co-authored-by: Jelle Zijlstra <[email protected]> (cherry-picked from commit 3024b16)
#124709) (#125211) Co-authored-by: Hugo van Kemenade <[email protected]> Co-authored-by: Barry Warsaw <[email protected]> Co-authored-by: Jelle Zijlstra <[email protected]>
and others
Documentation
Running sphinx-build in nit-picky mode, like:
or:
gives tons warnings. ~8k of them at the time of writing.
Most of them are innocent, like using
:const:while referring to a constant defined in another file, or using:meth:`__init__`to speak about the concept of an init method.The fall in several cases:
I don't have statistics (yet) on the distribution for the 4 previous cases.
For the innocent usages of rst markers, there's two fixes:
:const:`IGNORECASE`becomes``IGNORECASE``. We loose a bit of information in the rst file, I'm not fully convinced.:const:`IGNORECASE`becomes:const:`re.IGNORECASE`, or even:const:`~re.IGNORECASE`to keep the same output. It means more typing, and more links in the HTML output which are not all usefull.My question is: should we try to fix all warnings so we can easily spot typos at build time?
I tried to see if some typo would have been avoided by the nit-picky mode by reading a few pages of WARNINGS and found just one:
read1instead ofreadinbz2.rst.Linked PRs
enummodule #101122decimalmodule #102125decimalmodule (GH-102125) #102237decimalmodule (GH-102125) #102238typingmodule #102260typingmodule docs (GH-102260) #102262typingmodule docs (GH-102260) #102263typesmodule #102274typesmodule (GH-102274) #102291typesmodule (GH-102274) #102292turtlemodule #102340zipappandzipfilemodules #102526zipappandzipfilemodules (GH-102526) #102529zipappandzipfilemodules (GH-102526) #102530dismodule #102597turtlemodule (GH-102340) #102638turtlemodule (GH-102340) #102639argparsemodule #103289cursesandcurses.asciimodules #103457__format__instring.rst#103531argparsemodule (#103289) #103803cursesandcurses.asciimodules (GH-103457) #104124parse_argsinoptparse.rst#105265parse_argsinoptparse.rst(GH-105265) #106204parse_argsinoptparse.rst(GH-105265) #106205PyUnicode_RichCompare#106220PyTrace_*#106299URLErrorandHTTPErrorinhowto/urllib2.rst#107966threading.rst#108684threading.rst(GH-108684) #108707threading.rst(GH-108684) #108708tutorial/classes.rst#108746tutorial/appendix.rst#108750tutorial/classes.rst(GH-108746) #108755tutorial/classes.rst(GH-108746) #108756tutorial/appendix.rst(GH-108750) #108757tutorial/appendix.rst(GH-108750) #108759uuid.rst#108805uuid.rst(GH-108805) #108807uuid.rst(GH-108805) #108808unittest.mock-examples.rst#108810unittest.mock-examples.rst(GH-108810) #108812unittest.mock-examples.rst(GH-108810) #108813turtle.rst#109394turtle.rst(GH-109394) #109416turtle.rst(GH-109394) #109417tutorial/controlflow.rst#109424Doc/library/xml.etree.elementtree.rst#109799Doc/library/xml.etree.elementtree.rst(GH-109799) #109800Doc/library/xml.etree.elementtree.rst(GH-109799) #109801Doc/library/__future__.rst#109814Doc/library/weakref.rst#109881Doc/library/weakref.rst(GH-109881) #109883Doc/library/weakref.rst(GH-109881) #109884library/devmode.rst#109963library/devmode.rst(GH-109963) #109966library/devmode.rst(GH-109963) #109967library/difflib.rst#110074library/difflib.rst(GH-110074) #110081library/difflib.rst(GH-110074) #110082tutorial/controlflow.rst(GH-109424) #110084tutorial/controlflow.rst(GH-109424) #110085URLErrorandHTTPErrorinhowto/urllib2.rst(GH-107966) #110086URLErrorandHTTPErrorinhowto/urllib2.rst(GH-107966) #110087__enter__and__exit__#110112namedtuple#110113socketmethods #110114gettext#110115__getitem__#110118namedtuple(GH-110113) #110135namedtuple(GH-110113) #110136gettext(GH-110115) #110140gettext(GH-110115) #110141library/site.rst#110144library/site.rst(GH-110144) #110185library/site.rst(GH-110144) #110187library/socketserver.rst#110207library/getpass.rst#110461library/socketserver.rst(GH-110207) #110623library/socketserver.rst(GH-110207) #110624usage/cmdline.rst#110841usage/cmdline.rst(GH-110841) #110855usage/cmdline.rst(GH-110841) #110856library/time.rst#110862library/time.rst(GH-110862) #110877library/time.rst(GH-110862) #110878library/codecs.rst#110979library/codecs.rst(GH-110979) #111070library/codecs.rst(GH-110979) #111071library/getpass.rst(GH-110461) #111072__getitem__(GH-110118) #111073__getitem__(GH-110118) #111074__enter__and__exit__(GH-110112) #111075__enter__and__exit__(GH-110112) #111076library/tty.rst#111079library/getpass.rst(GH-110461) #111080library/tty.rst(GH-111079) #111097library/tty.rst(GH-111079) #111098fileno#111118tutorial/introduction.rst#111173tutorial/introduction.rst(GH-111173) #111175tutorial/introduction.rst(GH-111173) #111176library/asyncio-dev.rst#111179library/asyncio-dev.rst(GH-111179) #111185library/asyncio-dev.rst(GH-111179) #111186library/asyncio-eventloop.rst#111222fileno(GH-111118) #111226fileno(GH-111118) #111227library/asyncio-eventloop.rst(GH-111222) #111469library/asyncio-eventloop.rst(GH-111222) #111470whatsnew/2.0.rst#112351whatsnew/2.1.rst#112357whatsnew/2.2.rst#112366whatsnew/2.3.rst#112373test.regrtestmodule to fix references #112381_tkintermodule to fix references #112382test.regrtestmodule to fix references (GH-112381) #112390test.regrtestmodule to fix references (GH-112381) #112391_tkintermodule to fix references (GH-112382) #112392_tkintermodule to fix references (GH-112382) #112393library/doctest.rst#112399library/doctest.rst(GH-112399) #112402library/doctest.rst(GH-112399) #112404socketmethods (GH-110114) #112455socketmethods (GH-110114) #112456inspect.rst#112662inspect.rst(GH-112662) #112666inspect.rst(GH-112662) #112667library/gettext.rst#112668library/functions.rst#112669library/gettext.rst(GH-112668) #112673library/gettext.rst(GH-112668) #112674library/functions.rst(GH-112669) #112697library/functions.rst(GH-112669) #112698Doc/library/__future__.rst(GH-109814) #112701Doc/library/__future__.rst(#109814) #112702library/abc.rst#112703library/abc.rst(GH-112703) #112704library/abc.rst(#112703) #112705stdtypes.rst#112757stdtypes.rst(GH-112757) #112789stdtypes.rst(GH-112757) #112790library/reprlib.rst#112811library/reprlib.rst(GH-112811) #112813library/reprlib.rst(#112811) #112815ntpathorposixpathare referenced #112833library/shelve.rst#112836ntpathorposixpathare referenced (#112833) #112857ntpathorposixpathare referenced (#112833) #112858library/shelve.rst(GH-112836) #112868library/shelve.rst(GH-112836) #112869library/contextlib.rst#112870library/contextlib.rst(#112870) #112874library/contextlib.rst(#112870) #112875TracebackTypeattributes #112884library/tempfile.rst#112886library/tempfile.rst(#112886) #112910TracebackTypeattributes (GH-112884) #112911TracebackTypeattributes (GH-112884) #112912library/tempfile.rst(#112886) #112913library/traceback.rst#113106library/inspect.rstandreference/simple_stmts.rst#113107library/inspect.rstandreference/simple_stmts.rst(GH-113107) #113109library/inspect.rstandreference/simple_stmts.rst(GH-113107) #113110library/traceback.rst(GH-113106) #113111library/traceback.rst(GH-113106) #113112library/collections.abc.rst#113116mailboxdocs #113124library/rlcompleter.rst#113125library/collections.abc.rst(GH-113116) #113136library/collections.abc.rst(GH-113116) #113137whatsnew/2.3.rst(GH-112373) #113142whatsnew/2.3.rst(GH-112373) #113143mailboxdocs (GH-113124) #113144mailboxdocs (GH-113124) #113145library/rlcompleter.rst(GH-113125) #113158library/rlcompleter.rst(GH-113125) #113159library/numbers.rst#113162library/directory #113163library/numbers.rst(GH-113162) #113181library/numbers.rst(GH-113162) #113182library/directory (GH-113163) #113183library/directory (GH-113163) #113184library/ast.rst#113289library/ast.rst(GH-113289) #113290library/ast.rst(GH-113289) #113291howto/isolating-extensions.rst#113493c-api/float.rst#113494library/bisect.rst#113496howto/isolating-extensions.rst(GH-113493) #113497howto/isolating-extensions.rst(GH-113493) #113498library/calendar.rst#113500library/cmd.rst#113502library/bisect.rst(GH-113496) #113504library/bisect.rst(GH-113496) #113505library/calendar.rst(GH-113500) #113508library/calendar.rst(GH-113500) #113509library/cmd.rst(GH-113502) #113510library/cmd.rst(GH-113502) #113511c-api/structures.rst#113564library/configparser.rst#113598library/configparser.rst(GH-113598) #113599library/configparser.rst(GH-113598) #113600~!references #113629~!references (GH-113629) #113641~!references (GH-113629) #113642library/pyclbr.rst#113739library/pyclbr.rst(GH-113739) #113748library/pyclbr.rst(GH-113739) #113749Misc/#113946Misc/(GH-113946) #113998Misc/(GH-113946) #114001howto/urllib2.rstandlibrary/http.client.rst#114060howto/urllib2.rstandlibrary/http.client.rst(GH-114060) #114063howto/urllib2.rstandlibrary/http.client.rst(GH-114060) #114064reference/expressions.rst#114194Doc/c-api/memory.rst#114373Doc/c-api/memory.rst(GH-114373) #114377Doc/c-api/memory.rst(GH-114373) #114378Doc/library/locale.rst#114425reference/expressions.rst(GH-114194) #114436reference/expressions.rst(GH-114194) #114437asyncio-task.rst#114469Doc/library/locale.rst(GH-114425) #114477Doc/library/locale.rst(GH-114425) #114478asyncio-task.rst(GH-114469) #114518asyncio-task.rst(GH-114469) #114519concurrent.futures.rst#114521concurrent.futures.rst(GH-114521) #114525concurrent.futures.rst(GH-114521) #114526c-api/structures.rst(GH-113564) #114527whatsnew/3.11.rstand related #114531c-api/file.rst#114546c-api/file.rst(GH-114546) #114584c-api/file.rst(GH-114546) #114585library/email.mime.rst#114635library/email.mime.rst(GH-114635) #114640library/email.mime.rst(GH-114635) #114641reference/import.rst#114646whatsnew/3.11.rstand related (GH-114531) #114649whatsnew/3.11.rstand related (GH-114531) #114650reference/import.rst(GH-114646) #114652reference/import.rst(GH-114646) #114654Doc/c-api/memoryview.rst#114669library/enum.rst#114696Doc/c-api/memoryview.rst(GH-114669) #114704Doc/c-api/memoryview.rst(GH-114669) #114705whatsnew/2.2.rst(GH-112366) #114711whatsnew/2.2.rst(GH-112366) #114712c-api/gcsupport.rst#114786howto/logging.rst#114846howto/logging.rst(GH-114846) #114872howto/logging.rst(GH-114846) #114878load_moduleref #114982library/enum.rst(GH-114696) #115208library/enum.rst(GH-114696) #115209c-api/gcsupport.rst(GH-114786) #115263whatsnew/2.7.rstand related #115319whatsnew/2.7.rstand related (GH-115319) #115330whatsnew/2.7.rstand related (GH-115319) #115331c-api/gcsupport.rst(GH-114786) #115430whatsnew/3.1.rst#115575whatsnew/3.2.rst#115580whatsnew/3.1.rst(GH-115575) #115587whatsnew/3.1.rst(GH-115575) #115588whatsnew/3.2.rst(GH-115580) #115589whatsnew/3.2.rst(GH-115580) #115590whatsnew/2.0.rst(GH-112351) #115902whatsnew/2.0.rst(GH-112351) #115903whatsnew/2.1.rst(GH-112357) #115932whatsnew/2.1.rst(GH-112357) #115933library/pydoc.rst#116913library/pydoc.rst(GH-116913) #117037library/pydoc.rst(GH-116913) #117038library/faulthandler.rst#118353whatsnew/3.10.rst#118356whatsnew/3.9.rst#118364whatsnew/3.9.rst(GH-118364) #118365library/faulthandler.rst(GH-118353) #118366whatsnew/3.10.rst(GH-118356) #118367library/unittest.mock.rst#124106ModuleTypeattributes #124709library/unittest.mock.rst(GH-124106) #125190library/unittest.mock.rst(GH-124106) #125191ModuleTypeattributes (#124709) #125208ModuleTypeattributes (#124709) #125211The text was updated successfully, but these errors were encountered: