[Python-Dev] Re: Inline links in Misc/NEWS entries

> the talk I gave last month at PyOhio ( https://www.pyohio.org/2019/presentations/137) > Right now I have the slides up as a view-only share in my Google Drive ( bit.ly/bskinn-pyohio2019-intersphinx). Perhaps it would be useful to link to them? Or, to host a PDF someplace more permanent, and link

[Python-Dev] Re: Inline links in Misc/NEWS entries

- [ ] A page or section in the Sphinx docs would be helpful for many, I think https://github.com/sphinx-doc/sphinx/tree/master/doc ``__ .. index:: Implicit reference .. _implicit-reference: Implicit ref --- `implicit ref`_

[Python-Dev] Re: Inline links in Misc/NEWS entries

Citing from the current (19 Aug 2019) version of this PR (https://github.com/python/devguide/pull/525/files#diff-50cb76bbe8ae3fcd4170dc6e8d9d6b3fR225-R226): > Before using any Sphinx roles, ensure that a corresponding entry exists > within the documentation. At the risk of crass self-promotion,

[Python-Dev] Re: Inline links in Misc/NEWS entries

Based on the feedback from the ML thread and Discuss topic, I created a new PR on python/devguide which expands the "What's New and News Entries" section of "committing.rst" to include Sphinx roles: https://github.com/python/devguide/pull/525/files I would greatly appreciate feedback from contribu

[Python-Dev] Re: Inline links in Misc/NEWS entries

> a) this seems to be "well-defined", and imho, suitable as "easy", etc.. Part of this could potentially be suitable as an "easy" issue, but I'm not certain that it would make for a good first PR, since it is involving a fairly important and widely used section of the devguide. Many newcomers may

[Python-Dev] Re: Inline links in Misc/NEWS entries

On 16/08/2019 05:31, Kyle Stanley wrote: > Yeah definitely, it was my intention to mention this in the devguide, > particularly with adding an example of the Sphinx roles being used and > explaining appropriate usage. I hadn't thought of linking to the list of > roles (https://devguide.python.org/d

[Python-Dev] Re: Inline links in Misc/NEWS entries

> I suggest slightly expanding the part about NEWS formatting in the dev guide, and specifically have the example include appropriate uses of roles, and a link to the list of available roles. Yeah definitely, it was my intention to mention this in the devguide, particularly with adding an example

[Python-Dev] Re: Inline links in Misc/NEWS entries

I suggest slightly expanding the part about NEWS formatting in the dev guide, and specifically have the example include appropriate uses of roles, and a link to the list of available roles. https://devguide.python.org/committing/#what-s-new-and-news-entries On Thu, Aug 15, 2019 at 3:39 AM Kyle St

[Python-Dev] Re: Inline links in Misc/NEWS entries

> Also, for IDLE, news entries to idlelib/NEWS.txt > where markup, as opposed to unicode, is noise. Interesting, I actually wasn't aware of the distinction for idlelib/NEWS. I can imagine that Sphinx constructs such as :func:, :meth:, and :class: would not be nearly as useful there. However, I can

[Python-Dev] Re: Inline links in Misc/NEWS entries

On 8/13/2019 6:31 PM, Kyle Stanley wrote: The primary purpose of me creating this topic was because there seems to be some sentiment that it's perfectly fine to exclusively use plaintext in the news entries. Especially in cases where authors have rejected suggestions to adding the Sphinx marku

[Python-Dev] Re: Inline links in Misc/NEWS entries

> Could a bot be written to suggest upgraded markup for Misc/NEWS entries as a PR? Potentially, but to some degree, the decision of whether or not to use the Sphinx markup should be determined on a case by case basis, rather than indiscriminately applying the markup to every possible candidate. Ge

[Python-Dev] Re: Inline links in Misc/NEWS entries

> The ability to effectively use Python-specific Sphinx features in NEWS entries is a relatively new feature Ah, I think that would likely explain some of the inconsistent responses then. I think it would be worthwhile to add an example of using Sphinx and a brief explanation of when it can be use

[Python-Dev] Re: Inline links in Misc/NEWS entries

Could a bot be written to suggest upgraded markup for Misc/NEWS entries as a PR? Most e.g. class, method, and function references probably need ReST markup AND a more specific fully-qualified reference? Can class, method, and function lookups be done with the existing Sphinx API index? On Tuesda

[Python-Dev] Re: Inline links in Misc/NEWS entries

On Aug 13, 2019, at 15:31, Kyle Stanley wrote: > > In general, using many Python-specific Sphinx markup entities is fine: > > browsing though the consolidated blurb files for previous releases (and the > > resultant changelog html) shows uses of entities like :func: and :class:. > > Since it's

[Python-Dev] Re: Inline links in Misc/NEWS entries

> There seems to be some sentiment that it's perfectly fine to exclusively use plaintext in every news entry. Oops, that third sentence was a typo, I didn't intend to repeat myself there. On Tue, Aug 13, 2019 at 6:31 PM Kyle Stanley wrote: > > Note that there is an open devguide issue that requ

[Python-Dev] Re: Inline links in Misc/NEWS entries

> Note that there is an open devguide issue that requests improvements in the description of news entry processing Good to know, I'll look further into this issue and see if I can help with it. > In general, using many Python-specific Sphinx markup entities is fine: browsing though the consolidat

[Python-Dev] Re: Inline links in Misc/NEWS entries

On Aug 13, 2019, at 00:20, Kyle Stanley wrote: > On Tue, Aug 13, 2019 at 2:41 AM Mariatta wrote: > > I would like to understand why some developers dislike including it, even > > when the reST syntax is provided. > > This has something to do with the use of blurb/blurb-it. Both tools > specif

[Python-Dev] Re: Inline links in Misc/NEWS entries

> * The BODY section should be a single paragraph of English text in ReST format. It should not use the following ReST markup features: > * section headers > * comments > * directives, citations, or footnotes > * Any features that require significant line breaks, like lists, definition lists, quote

[Python-Dev] Re: Inline links in Misc/NEWS entries

> I would like to understand why some developers dislike including it, even when the reST syntax is provided. This has something to do with the use of blurb/blurb-it. Both tools specifically say "single paragraph with simple ReST markup". Further reading blurb's source code, it says the format of