On 1 May 2017 at 06:37, Nick Coghlan <ncogh...@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`_``. _______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
