Header field for link to final outcome (e.g. documentation)?

[brettcannon]

#2690 pushed a thought into my head about whether it would be helpful to have a link in the PEP to what the PEP led to (e.g. documentation link for what was added thanks to the PEP)? Maybe the rendering could emphasize that so people realize the link is now the canonical place for details and the PEP has become a historical document (for Standards Track PEPs)?

I'm basically trying to help guide users to not submit PRs here for updating examples and such and instead work to improve the actual outcome of the PEPs.

[CAM-Gerlach]

Funny enough, it was your own #2684 that in turn inspired that PR 😄

This would be a great idea, since this would not only redirect traffic here to more appropriate places, but also be a great informational resource for readers to quickly jump to the up to date, user-oriented version of whatever the PEP describes, and also help authors and ourselves keep track that we are actually providing such resources whenever appropriate (and identify PEPs missing them). Indeed, that PR had me thinking of something along those lines myself.

Only issue with adding another header is the continued expansion in the number of rendered headers (though they take up way less space now), which @gvanrossum no likey, and it would be easy to miss amongst a bunch of other headers, especially for users (i.e. most of the target audience here) that are less familiar with the PEP process.

One potential alternative is instead of having a header (or at least having it render as a header), instead have a custom directive that renders an admonition like on #2690 with a standardized message that includes the doc/etc. link at the top of the PEP, which would be a lot easier to spot and also allow a brief mention that the PEP is a historical document, etc, as well as any desired custom PEP-specific text.

Here's a rough sketch of what it could look like, for (picked at random) PEP-553:

.. canonicalcontent:: https://docs.python.org/3/library/functions.html#breakpoint

which could render as:

We could have directive options and/or subclasses as needed for specific types of docs, like packaging, and any desired custom text could be added between the first and second lines underneath the directive, just like with e.g. versionadded and deprecated in the CPython docs.

[brettcannon]

A directive would be a great solution!

[AA-Turner]

Agree on a directive. I'd also vote to keep as simple as possible -- perhaps even make the entire div a link target (the horror!)

A

[CAM-Gerlach]

Okay, great! I'll go ahead with a PR, then. If it gets merged before #2690 , I'll update that one to use a PyPA-specific version of this directive instead of manual admonitions, otherwise I'll merge that as is and do it once this one's in.

perhaps even make the entire div a link target (the horror!)

Hmm, that's an interesting thought to make the target easier to find/click—but it would preclude multiple links, which both the generic example and the packaging ones have, isn't typical behavior users expect from admonitions, and would be somewhat more work to implement; with the above I can just create a normal admonition with the specified content, basically.

[pradyunsg]

One thing with the directive is that a PEP might end up in multiple documentation locations (to use Diataxis terms, a tutorial, reference and explanation).

IMO, it would make sense to allow the directive to take multiple URLs as a body as well.

[CAM-Gerlach]

IMO, it would make sense to allow the directive to take multiple URLs as a body as well.

Yup, the idea is to allow arbitrary custom reST text (which can include links, etc) in the body of the directive, which then gets included in the admonition after the first line.

[CAM-Gerlach]

I've added both a standard canonical-content directive and a canonical-content-pypa subclass with a variety of capabilities requested here and opened it as #2702 .

[pradyunsg]

FWIW, I’ve been wondering if making this a page-wide sticky banner, rather than an admonition at the top of the document would be useful. That way, we’d have a pointer to the canonical content even when someone links to a specific section in the PEP.

[CAM-Gerlach]

That's a good point, but IMO that might be a little too overbearing at least for most PEPs and cause much more friction when adding the banner (as there already was some on the PR), since there are still legitimate reasons to read them rather than the canonical documentation/spec even if they are historical. We could make it apply to just the pypa subclass, though that might seem a little inconsistent.

Also, as a practical matter, it is a substantial increase in implementation complexity (and styling bikeshedding) vs. using a standard reST admonition, so I'd rather merge the notice as a banner first and then we could that as a followup.