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. |
* pythongh-101100: [Enum] Fix sphinx warnings in (cherry picked from commit 9e025d3) Co-authored-by: Nikita Sobolev <mail@sobolevn.me> Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
|
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. |
…) (#117037) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
…) (#117038) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
* clean up fcntl module doc * simplify * a few changes, based on suggestion by CAM-Gerlach * nitpick ignore for a couple other C functions mentioned in the fcntl module doc * more changes, especially related to LOCK_* constants * :data: back to :const: * Apply suggestions from code review Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM> --------- Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
…2357) Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu> Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
…5580) Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
…2351) Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
* clean up fcntl module doc * simplify * a few changes, based on suggestion by CAM-Gerlach * nitpick ignore for a couple other C functions mentioned in the fcntl module doc * more changes, especially related to LOCK_* constants * :data: back to :const: * Apply suggestions from code review Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM> --------- Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
…2357) Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu> Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
…thonGH-118364) (cherry picked from commit e0ab642) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
…ythonGH-118353) (cherry picked from commit 33c6cf3) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
…) (#118367) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
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) #118367The text was updated successfully, but these errors were encountered: