Sub-index pages for specific categories of PEPs (Packaging, etc)

[pradyunsg]

See https://discuss.python.org/t/14111/, where this was discussed initially and where folks have been generally in favour of this.

It would be valuable to be able to list PEPs related to Python Packaging, in a single location in addition to having them in the PEP 0 index. While packaging.python.org could have such a list (and it does, to an extent), that has an additional maintainance burden (it needs to be updated each time a new PEP is proposed). It would be more beneficial to be able to provide such a listing under peps.python.org. This has discoverability advantages, will be easier to maintain (since the PEP sources themselves will note that it's a Packaging-related PEP) and avoids needing to update two spots when a new Packaging-related PEP is proposed.

[pradyunsg]

A concrete proposal for implementing this, roughly based on the concensus in the aforementioned thread, is:

• Add an optional Track header for PEPs, that can have only one value for the initial implementation: Packaging.
  • Add this header to existing Python Packaging PEPs.
• Add a track-specific index page, that lists all PEPs with that track: peps.python.org/track/packaging
  • This page should have a different header and introduction section than PEP 0.

The Track header can be expanded to other values in the future (Typing and Release are examples of proposed ideas from the aforementioned thread).

Personally, I think it's valuable to implement this for just Packaging as an initial pass since it's a viable "minimum" implementation of this mechanism and... perhaps more importantly... avoids an extended discussion on what these other values should be allowed/updated for. :)

[AA-Turner]

I'm supportive of the idea.

Implementation-wise it wouldn't be challenging & happy to pick it up if we agree.

I'd suggest using the index namespace, as it's recognised that PEP 0 is the index, and this is in effect a 'sub-index' -- so peps.python.org/pep-0000/packaging.

A

[brettcannon]

I support this.

I'd suggest using the index namespace, as it's recognised that PEP 0 is the index, and this is in effect a 'sub-index' -- so peps.python.org/pep-0000/packaging

I actually don't know if most people realize there is a PEP 0 and that it's the index.

[pradyunsg]

I'd suggest using the index namespace, as it's recognised that PEP 0 is the index, and this is in effect a 'sub-index' -- so peps.python.org/pep-0000/packaging

I don't have strong feelings on the exact URL, so whatever PEP editors prefer works for me!

[AA-Turner]

I actually don't know if most people realize there is a PEP 0 and that it's the index.

Fair enough -- I suppose I'm approaching the issue somewhat with an implementation bias, too.

But if that's the worst thing we can argue about... 😉

A

[hugovk]

I also support this!

peps.python.org/pep-0000/packaging looks a little odd as well, something like peps.python.org/track/packaging feels a lot more intuitive.

[pradyunsg]

Looking at the implementation generating the index page, currently, PEP 0 is generated in pep_sphinx_extensions/ by adding a hook that generates the entire file in-memory. This file is then populated with the relevant content, as generated in PEPIndexWriter, written and then added to the Sphinx's various internal lists to ensure that it builds it appropriately.

It would be feasible to have pep-0000.rst be a regular file that's checked into the repository, if it used a custom reST directive that populates the index part of the file. The header and introduction can then be kept in the source, as prose, outside of the Python code (they're in a writer.py file currently).

This could make having a separate index easier, since the parts that need to differ (header and introduction) can live outside the Python generator, which would also (possibly?) simplify to "only" have a directive for the index generation -- i.e. hook into Sphinx's build system to a lesser extent.

I'm not super familiar with the Sphinx-based PEP generation code though and what constraints it was written with, so if this is not feasible for some reason, I apologise for my ignorance. 😅

PS: PEPIndexWriter doesn't actually write the file. It might be a good idea to rename it to PEPIndexGenerator or something. :)

[JelleZijlstra]

Another bikeshed :)

"Track" may not be the best term, because it's really only applicable to packaging, where PEPs go through a very different process from other PEPs. Typing PEPs are on the same "track" as regular PEPs, because they get discussed on python-dev and approved by the SC just like any other PEP. Alternative suggestion: "Area". Then we could have headers like "Area: Packaging", "Area: Typing", "Area: Release", and automatically generate pages for each of these areas.

For now we'd start with just "Area: Packaging", and if the community is interested in a new Area, we could add it later.

[hugovk]

There is a bit of overlap in naming here:

The PEP Type can be Standards Track, Informational, or Process.

https://peps.python.org/pep-0001/#pep-types

Track is only applied to one of the types, but track does also feel the right name for this new field. Maybe it doesn't matter?

[AA-Turner]

Topic? Area also seems reasonable.

We could also be very boring and have Index:.

A

[AA-Turner]

I re-titled the issue as although packaging will be first, the design needs to be sufficiently general for other potential sub-indicies.

A