[Python-Dev] Escaping docs markup in NEWS entries?

[Martin Panter]

On 1 May 2017 at 06:37, Nick Coghlan <ncoghlan at gmail.com> wrote:
> Hi folks,
>
> I'm trying to write a NEWS entry that explains that the
> ":func:`bytes`" cross-references have changed to refer to the type
> descriptions by default (matching other builtin container types), so
> you now need to use ``:ref:`func-bytes`" to refer to the old target in
> the list of builtin functions (if you really want that for some
> reason).
>
> Unfortunately, my first two attempts both cause warnings in "make
> suspicious" with the following output:

What is the full output? Usually it includes instructions to add false
positives to Doc/tools/susp-ignored.csv; maybe that is all you have to
do?

> ------------
> WARNING: [whatsnew/changelog:986] ":func" found in "\:func\:\`bytes\`"
> WARNING: [whatsnew/changelog:986] "`" found in "\:func\:\`bytes\`"
> WARNING: [whatsnew/changelog:986] ":func" found in "\:func\:\`bytearray\`"
> WARNING: [whatsnew/changelog:986] "`" found in "\:func\:\`bytearray\`"
> WARNING: [whatsnew/changelog:986] ":ref" found in "\:ref\:\`func-bytes\`"
> WARNING: [whatsnew/changelog:986] "`" found in "\:ref\:\`func-bytes\`"
> WARNING: [whatsnew/changelog:986] ":ref" found in "\:ref\:\`func-bytes\`"
> WARNING: [whatsnew/changelog:986] "`" found in "\:ref\:\`func-bytes\`"
> ------------
>
> My first attempt just escaped the nested backticks:
>
> - Issue #30052: the link targets for ``:func:\`bytes\``` and
>   ``:func:\`bytearray\``` are now their respective type definitions, rather
>   than the corresponding builtin function entries. Use ``:ref:\`func-bytes\```
>   and ``:ref:\`func-bytes\``` to reference the latter.
>
> My second attempt escaped the colons as well:
>
> - Issue #30052: the link targets for ``\:func\:\`bytes\``` and
>   ``\:func\:\`bytearray\``` are now their respective type definitions, rather
>   than the corresponding builtin function entries. Use ``\:ref\:\`func-bytes\```
>   and ``\:ref\:\`func-bytes\``` to reference the latter.
>
> My fallback plan is to just include the unescaped markup in the NEWS
> entry (rather than trying to make it readable even in rendered form),
> but I figured I'd ask for advice here first.

I thought the NEWS file was mainly regarded as plain text, so it would
be important to avoid ugly RST markup like backslashes if possible.

I am no RST expert, but perhaps it would be clearer to a human RST
parser if you added a space among the last three backticks, where the
underscore is in ``:func:`bytes`_``.