Document Metadata fields and format for the Upload API

[alanbato]

This should fix the problem stated in #3151.
This is a WIP and the changes mentioned here have not been added yet.

Any comments/ideas/questions on the format and content are welcome 😃

PS. make docs isn't working for me, it complains about sphinx not being installed inside the venv 😅

Pinging @brainwane and @di for review.

🐍 📦 📝

[brainwane]

For reference -- we chatted about this in today's Warehouse livechat.

[brainwane]

@alanbato how is this going?

[di]

Just explicitly requesting changes on this, as mentioned here: #3151 (comment)

[brainwane]

@alanbato How's this going?

[abitrolly]

I think this should be merged. It improves API documentation a lot. Validation and corrections can be added in a separate good first issue.

[abitrolly]

@di is it possible to reticket description of dependency fields as a separate issue? There are a lot of questions about them. Like if they are stored, then where they are exposed in API, why we still need #8254, etc.

[dstufft]

There is now PEP 694: Upload 2.0 API for Python Package Repositories, which has discussions on discuss.python.org which is relevant to this issue.

[di]

Closing this in favor of eventually documenting this via a PEP, like https://peps.python.org/pep-0694/.

[abitrolly]

@di maybe close this when the documentation is done? Otherwise there is no way to track it.

[di]

This is being tracked in #3151.