Show the repr of the value in some warnings.

[ezio-melotti]

Subject: Show the repr of the value in some warnings

Feature or Bugfix

• Refactoring

Purpose

• This PR uses %r to display values in some warning messages.

Detail

• Show repr of the value in warnings #10438

Note that I only fixed sphinx/domains/std.py and the tests that failed after the fix.
There are similar warnings in other files that could be changed.
A test specific for trailing spaces could be added, but I'm not sure where.

[AA-Turner]

Seems reasonable, although this probably needs a CHANGES entry.

Where else were you thinking of changing from str -> repr?

A

[ezio-melotti]

Where else were you thinking of changing from str -> repr?

I've seen a few more that seem related by looking for dangling_warnings, e.g.:

sphinx/sphinx/domains/citation.py

Lines 30 to 32 in 1222bed

	dangling_warnings = {
	'ref': 'citation not found: %(target)s',
	}

sphinx/sphinx/domains/math.py

Lines 40 to 42 in 1222bed

	dangling_warnings = {
	'eq': 'equation not found: %(target)s',
	}

Searching for logger.warning yields plenty of results too.

Searching for unknown yields some more, like:

sphinx/sphinx/domains/c.py

Line 171 in 1222bed

raise Exception('Unknown description mode: %s' % mode)

and several others (some even use '...: "%s".' % value), but I'm not sure if these are related, since I'm not too familiar with the codebase.

I only fixed std.py to keep the PR focused and get some initial feedback. If you think I should fix more messages and add the CHANGES entry just let me know.

[tk0miya]

As I commented at #10438 (comment), these target can contain a single quote. So -0 for changing this.

[ezio-melotti]

Python's repr uses single quotes by default and switches to doubles quote if the string already contains single quotes. If the string contains both, it will use single quotes and escape any single quote in the string:

>>> print(repr(""" "only double quotes" """))  # output uses single quotes
' "only double quotes" '
>>> print(repr(""" 'only single quotes' """))  # output uses double quotes
" 'only single quotes' "
>>> print(repr(""" "mixed" 'quotes' """))  # output uses single quotes + escapes
' "mixed" \'quotes\' '

Therefore, with the changes in my PR, the following markup:

:ref:`Documenting Python <invalidlabel>`
:ref:`in-development <in"dev"branch>`
:ref:`maintenance <maint'branch>`
:ref:`Quick Guide to Pull Requests <pull"request"-quick'guide>`
:doc:`pull request <pull'request>`
:ref:`contributor agreement < cla>`
:doc:`pull request <pullrequest >`

will trigger these warnings:

devguide/docquality.rst:18: WARNING: undefined label: 'invalidlabel'
devguide/docquality.rst:33: WARNING: undefined label: 'in"dev"branch'
devguide/docquality.rst:33: WARNING: undefined label: "maint'branch"
devguide/docquality.rst:62: WARNING: undefined label: 'pull"request"-quick\'guide'
devguide/docquality.rst:107: WARNING: unknown document: "pull'request"
devguide/docquality.rst:112: WARNING: undefined label: ' cla'
devguide/docquality.rst:129: WARNING: unknown document: 'pullrequest '

Only the fourth example (that contains both single and double quotes) includes an escaped \'.
The last two examples show leading and trailing spaces -- now clearly visible thanks to the repr.

For comparison, without using the repr, it produces these warnings:

devguide/docquality.rst:18: WARNING: undefined label: invalidlabel
devguide/docquality.rst:33: WARNING: undefined label: in"dev"branch
devguide/docquality.rst:33: WARNING: undefined label: maint'branch
devguide/docquality.rst:62: WARNING: undefined label: pull"request"-quick'guide
devguide/docquality.rst:107: WARNING: unknown document: pull'request
devguide/docquality.rst:112: WARNING: undefined label:  cla
devguide/docquality.rst:129: WARNING: unknown document: pullrequest 

Note that it's difficult to notice the extra spaces in the last two examples (especially in the last one).

[AA-Turner]

@ezio-melotti please add a CHANGES entry.

A

[ezio-melotti]

Thanks for taking care of the CHANGES entry and merging this!