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

Wes Turner wes.turner at gmail.com
Mon May 1 06:03:59 EDT 2017


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

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>



More information about the Python-Dev mailing list