Skip to content

Fix all Sphinx reference warnings in the documentation #101100

@JulienPalard

Description

@JulienPalard

Documentation

Running sphinx-build in nit-picky mode, like:

sphinx-build -n . build/html/

or:

make html SPHINXERRORHANDLING=-n

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:

  • The target is not documented at all, then document it, like in 664aa94
  • There's a typo, then fix it.
  • We're mentionning something that does not exists (or no longer exists), then rewrite.
  • Innocent usage of rst markers without the intention of linking to something, then ???

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:

  • Drop the role, :const:`IGNORECASE` becomes ``IGNORECASE``. We loose a bit of information in the rst file, I'm not fully convinced.
  • Make it point to something existing, :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 of read in bz2.rst.

Linked PRs

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsDocumentation in the Doc direasy
    No fields configured for issues without a type.

    Projects

    Status

    Todo

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions