[Python-Dev] Escaping docs markup in NEWS entries? (original) (raw)

Martin Panter vadmium+py at gmail.com
Mon May 1 03:13:25 EDT 2017

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

More information about the Python-Dev mailing list