-
-
Notifications
You must be signed in to change notification settings - Fork 30.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
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]>
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:
read1
instead ofread
inbz2.rst
.Linked PRs
enum
module #101122decimal
module #102125decimal
module (GH-102125) #102237decimal
module (GH-102125) #102238typing
module #102260typing
module docs (GH-102260) #102262typing
module docs (GH-102260) #102263types
module #102274types
module (GH-102274) #102291types
module (GH-102274) #102292turtle
module #102340zipapp
andzipfile
modules #102526zipapp
andzipfile
modules (GH-102526) #102529zipapp
andzipfile
modules (GH-102526) #102530dis
module #102597turtle
module (GH-102340) #102638turtle
module (GH-102340) #102639argparse
module #103289curses
andcurses.ascii
modules #103457__format__
instring.rst
#103531argparse
module (#103289) #103803curses
andcurses.ascii
modules (GH-103457) #104124parse_args
inoptparse.rst
#105265parse_args
inoptparse.rst
(GH-105265) #106204parse_args
inoptparse.rst
(GH-105265) #106205PyUnicode_RichCompare
#106220PyTrace_*
#106299URLError
andHTTPError
inhowto/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) #110085URLError
andHTTPError
inhowto/urllib2.rst
(GH-107966) #110086URLError
andHTTPError
inhowto/urllib2.rst
(GH-107966) #110087__enter__
and__exit__
#110112namedtuple
#110113socket
methods #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.regrtest
module to fix references #112381_tkinter
module to fix references #112382test.regrtest
module to fix references (GH-112381) #112390test.regrtest
module to fix references (GH-112381) #112391_tkinter
module to fix references (GH-112382) #112392_tkinter
module to fix references (GH-112382) #112393library/doctest.rst
#112399library/doctest.rst
(GH-112399) #112402library/doctest.rst
(GH-112399) #112404socket
methods (GH-110114) #112455socket
methods (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) #112815ntpath
orposixpath
are referenced #112833library/shelve.rst
#112836ntpath
orposixpath
are referenced (#112833) #112857ntpath
orposixpath
are referenced (#112833) #112858library/shelve.rst
(GH-112836) #112868library/shelve.rst
(GH-112836) #112869library/contextlib.rst
#112870library/contextlib.rst
(#112870) #112874library/contextlib.rst
(#112870) #112875TracebackType
attributes #112884library/tempfile.rst
#112886library/tempfile.rst
(#112886) #112910TracebackType
attributes (GH-112884) #112911TracebackType
attributes (GH-112884) #112912library/tempfile.rst
(#112886) #112913library/traceback.rst
#113106library/inspect.rst
andreference/simple_stmts.rst
#113107library/inspect.rst
andreference/simple_stmts.rst
(GH-113107) #113109library/inspect.rst
andreference/simple_stmts.rst
(GH-113107) #113110library/traceback.rst
(GH-113106) #113111library/traceback.rst
(GH-113106) #113112library/collections.abc.rst
#113116mailbox
docs #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) #113143mailbox
docs (GH-113124) #113144mailbox
docs (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.rst
andlibrary/http.client.rst
#114060howto/urllib2.rst
andlibrary/http.client.rst
(GH-114060) #114063howto/urllib2.rst
andlibrary/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.rst
and 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.rst
and related (GH-114531) #114649whatsnew/3.11.rst
and 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_module
ref #114982library/enum.rst
(GH-114696) #115208library/enum.rst
(GH-114696) #115209c-api/gcsupport.rst
(GH-114786) #115263whatsnew/2.7.rst
and related #115319whatsnew/2.7.rst
and related (GH-115319) #115330whatsnew/2.7.rst
and 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
#124106ModuleType
attributes #124709library/unittest.mock.rst
(GH-124106) #125190library/unittest.mock.rst
(GH-124106) #125191ModuleType
attributes (#124709) #125208ModuleType
attributes (#124709) #125211The text was updated successfully, but these errors were encountered: