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

[Nick Coghlan]

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:

------------
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.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia