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
Feel free to take it, I don't think I'll have time for this soon.

IMO, we should fix these. Many are actual issues in the documentation.

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 sqlite3 module that Erlend and I fixed.

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.

I'd argue neither is exactly innocent:

• For the first, unless there's some particular reason not to, it usually makes sense to actually cross reference the constant, so the reader can find out more, and be explicit about it's location at least in the source (since ~ can hide that in the rendered output if not desired). This also means if the constant is renamed, moved or removed, Sphinx will issue a warning about it.
• For the second, doing :meth:`~object.__init__` to cross reference the full description of an __init__ method will often still have value to readers, at least on first usage in a context, and doesn't take up any more space. We could potentially extend the :meth: role to automatically prepend a default name, i.e. object, to :meth: and :attr: that only have a single component, and perform the lookup with that—though the Sphinx built in roles are not the best structured to be able to extend easily without copying a fair bit of code.

For the innocent usages of rst markers, there's two fixes:

There's a third, much simpler and better fix. If the link isn't desired, every Sphinx cross-reference role supports prepending ! to prevent Sphinx from trying to resolve the reference, which avoids both the warning and the (very slight) build-time lookup cost, while preserving both all the information in the source, and the formatting in the output (since the formatting of named roles and regular literals is not the same, at least in our current theme), while being easier than both (just add one character). So, you could just do:

:const:`!IGNORECASE`

I've sent an example PR with the fix for enum module: #101122

The dev experience was plesant, because on the second run sphinx only rebuilds (and warns about) changed files:

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.

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 decimal module: #102125

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 -n mode seems secondary to me to ensuring they are clear, helpful and consistent for readers, per Diataxis on the overall function of reference docs, particularly since CPython itself doesn't build the docstrings. If the latter can be satisfied while serving the former purpose and being enough of a non-trivial and thoughtful improvement to not quality as mechanical churn, then it would seem to me to have net value.

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.

Would it be possible for the warning to include a link to possible fixups for the particular warning? I don't remember reading about '~object' or '!CON' and I imaging others are similarly deficient in sphinx-fu.

Would it be possible for the warning to include a link to possible fixups for the particular warning?

That would be a great idea, but its kinda hard to programmatically determine the most appropriate solution for a particular case without considering the specifics and context of the situation, which can be very quick for a human like us with the specific expertise and experience (really, the latter more than the former, since the syntax can be a lot easier to grasp than the semantics) but much harder to write reliable prescriptive rules for.

IMO, it would be better for most folks to just not worry about it at all and instead just tag a docs team member (like me) and we can pop over and make a one-click suggestion (or commit) with the best fix if desired. For these kind of issues, I can have a <24 hour, perhaps close to 12-hour SLA.

I don't remember reading about '~object' or '!CON' and I imaging others are similarly deficient in sphinx-fu.

@ezio-melotti made a nice quick-reference table with all of the common syntax bits, including those, over on the devguide, and the Sphinx docs also has a concise primer covering those as well, but TL;DR these are the main cases:

• If the object exists and should be formally documented but isn't, either document it or leave the warning until it is

• If an object exists but is unintentionally broken due to the wrong class, module, etc. prefix, a typo, etc, fix it

• If an object is missing an implicit prefix that should not be displayed in the final output, like object for dunder methods or the class name when methods are listed individually, add the prefix with a prepended a ~ to hide it (e.g. :meth:`~object.__str__`, the :meth:`~Spam.get_foo` method of the :class:`Spam` class)

• If an object was removed from Python, is deliberately undocumented or is a subsequent reference to something already linked in the the same scope, prepend ! to not resolve the reference (e.g. :meth:`!Spam.removed_method`, :c:func:`!_internal_api`)

• If an object is an example or not otherwise a "real" class, function, etc., either do the above or use a literal (e.g. ``ExampleClass.example_attr`` ``fake_func()``).