improve pipeline for user-facing feature-specific documentation

[brainwane]

This doesn't need to block this PR, but I've wondered if our propensity for linking to PEPs is the best user experience we can provide here, or if we should figure out a real documentation pipeline for Warehouse (not really counting what exists now since it's primarily developer facing documentation, not user facing) and start moving to that.

Originally posted by @dstufft in #5838

Donald, could you talk a little more about what you mean re: a documentation pipeline for user-facing docs? Right now we have:

• packaging.python.org
• the help/FAQ page on PyPI
• warehouse.readthedocs.io/ which does have user-facing stuff for the API, for instance

Am I right in understanding that you want a better system for inline/contextual instructions and other docs to display within features?

[dstufft]

What I'm thinking of would probably replace the help/FAQ page on PyPI, and would be user facing documentation specific to PyPI. It might be a reasonable place t move the user facing API docs too, or that might be better being housed in targeted API doc, I dunno.

Mostly it seems like we have features we want to document on PyPI, and we currently don't really have a great answer for documenting those things. We kind of do a mish mash of adding things to our help/FAQ page (which is getting increasingly lengthy and cumbersome to organize), linking directly to PEPs (which really isn't the purpose of a PEP, they're change management not long term documentation), packaging.python.org (which sort of works, but is a separate repository so the dev experience isn't the greatest but that's maybe fine), and warehouse.readthedocs.io (which sort of holds api docs, but we basically ignore this documentation).

Roughly to me it feels like documentation for PyPI for an end user is kind of a hodge podge of places, and I think that's because we don't really have a canonical answer for where PyPI gets documented at. This would roughly equal to pip.pypa.io, but for PyPI.

[pradyunsg]

#5947 stands out as a case that'd benefit from something like this.

[woodruffw]

Triage: https://docs.pypi.org now exists, with user-focused documentation.

This includes both the API docs (which were migrated from the dev-docs) as well as some of the information that was previously in help.html (not all yet, I'm working on that!).

As such, I think this can be closed, since the remaining items are piecemeal (the new doc structure exists, just needs to be rounded out)!