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

[Nick Coghlan]

On 1 May 2017 at 17:13, Martin Panter <vadmium+py at gmail.com> wrote:
> 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?

You're right, that would be likely be the way to go if I decided to
keep the escaped markup.

However...

>> 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 think you're right on this point, so it makes more sense to skip
the escaping entirely,
and just use the correct link markup in the NEWS entry.

Cheers,
Nick.

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