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

[Wes Turner]

Where would be a good place for test cases for an rst_escape() function?
Docutils?

https://github.com/westurner/dotfiles/blob/develop/scripts/git-changelog.py

- rst_escape # YMMV
- $ git-changelog.py -r "release/0.3.14" --hdr= "+"`

On Monday, May 1, 2017, Nick Coghlan <ncoghlan at gmail.com> wrote:

> On 1 May 2017 at 17:13, Martin Panter <vadmium+py at gmail.com <javascript:;>>
> wrote:
> > On 1 May 2017 at 06:37, Nick Coghlan <ncoghlan at gmail.com <javascript:;>>
> 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.

How convenient.

>
> Cheers,
> Nick.
>
> --
> Nick Coghlan   |   ncoghlan at gmail.com <javascript:;>   |   Brisbane,
> Australia
> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org <javascript:;>
> https://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: https://mail.python.org/mailman/options/python-dev/
> wes.turner%40gmail.com
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20170501/1ccd53fb/attachment.html>