Reworded the section about predictable URLs

[flying-sheep]

In #5535 it became clear that the current state of the documentation misleads people into thinking the predictable URL API might me some kind of barely maintained step child instead of the valuable asset for Linux package maintainers that it is.

Rendered

[flying-sheep]

I’m confused about python_tag (the specified part in wheels) vs python_version (the part in the URLs after /packages/ that’s mostly “source”, or the python_tag, but sometimes something else entirely)

Is there a spec for this? Why do some wheels have some freeform stuff in there even though their python_tag is correct?

• coverage-config-reload-plugin has python_tag=py2.py3 and python_version=any
• numericalunits and tbvaccine have python_tag=py2.py3 and python_version=3.6

Is that a bug in the consistency check of PyPI? Or is it allowed to have differing versions there?

There needs to be one of two things:

1. Either I need an explanation for python_version
2. Or we need to patch the redirection so it also makes wheels available under /packages/{python_tag}/... instead of having to figure out their bogus python_version.

[flying-sheep]

PS: the travis failure is a bug in the validation: :pep:`number#anchor` is valid syntax.

[pradyunsg]

Sounds like a good bugfix PR for doc8. :)

[miketheman]

#Triage
Surfacing this for reevaluation. Generally speaking, the docs update seems reasonable, but we've since changed CI providers since this was authored, and there's some conflicts that need to be resolved.

@flying-sheep are you still interested in making this contribution?

[flying-sheep]

Sure, why not!