docs/api: clean up Upload API docs slightly

[woodruffw]

This is an attempt to clean up the Upload API docs (very) slightly, as well as document some other well-known edge cases/discrepancies between the metadata layout and the POST form layout.

Key changes:

• Made formatting more uniform: list items now mostly start with the field they're describing, instead of describing the field in free-form prose.
• Elaborated on the description of how metadata is transformed into form fields, including a description of how multiple-use fields are pluralized (Classifier -> classifiers). Also added a table visualizing the different cases.
• Added a clarifying link about the format of pyversion Python tags.
• Replaced i.e. with e.g. where appropriate.

I think this (along with the other recent upload API doc changes) is sufficient to close #3151 🙂

[di]

I'm not sure if this is exactly true or if there are some edge cases. I haven't looked closely but some fields are getting mapped here while others like classifier/classifiers aren't:

warehouse/warehouse/forklift/metadata.py

Lines 270 to 276 in 80d26fd

	# Map Form fields to RawMetadata
	_override = {
	"platforms": "platform",
	"supported_platforms": "supported_platform",
	"license_files": "license_file",
	}
	_FORM_TO_RAW_MAPPING = {_override.get(k, k): k for k in _RAW_TO_EMAIL_MAPPING}

[woodruffw]

Yeah, this is confusing: _RAW_TO_EMAIL_MAPPING contains the classifier -> classifiers pluralization as expected, but then _FORM_TO_RAW_MAPPING overrides that pluralization for those three cases.

In other words, the mapping for License-File goes:

1. "Email" representation: License-File
2. "pyproject" representation: license-files
3. "Raw" representation: license_files
4. "POST form" representation: license_file

As best I can tell representation (1)-(3) are defined in PEP 639, while representation (4) is a bit of a wild west (since it's particular to PyPI's upload API, not packaging standards). In the case of license_file it looks like Hatch was the earliest adopter and chose not to pluralize the form field, so other implementations have followed suit:

• twine also uses license_file, probably following Hatch: https://github.com/pypa/twine/blob/353e0e4e2b02acedff37d00d52f26de056e33e55/twine/package.py#L152

TL;DR: As best I can tell these three fields are the only exceptions to the "multi-use fields get pluralized in the POST form representation" rule, so I'll update the docs to reflect that.

CC @ofek @brettcannon for thoughts as well 🙂

[woodruffw]

Other context:

• PEP 639 followup #17105
• Correctly handle (lack of) pluralization in license_file upload data #17106