Add examples to metadata in pyproject.toml page

[FFY00]

PEP 621 defines a standard format for package metadata in pyproject.toml. I expect several backends to implement it, but not all to produce high quality documentation on how to use it, specially small domain-specific backends. It would be great to have a tutorial/description of the fields packaging.python.org that backends could point users to. Right now, the best option is to point to the PEP itself.

[henryiii]

Would it be best to add right after or simultaneously with either setuptools or the first implementing backend? (cibuildwheel is sort-of first, but only for requires-python ;) ) It's going to be rather confusing if there's a guide for something but it can't be used yet.

[FFY00]

I was envisioning this more like a separate page backends could point to. The setuptools documentation could show an example, as it is fairly straightforward, and have a link to the full documentation for more details.

[domdfcoding]

I semi-rewrote PEP 621 as part of the docs for whey (see https://whey.readthedocs.io/en/latest/configuration.html), removing the parts aimed at backend authors and adding examples for each field.

Is that the sort of thing you were thinking of?

[pradyunsg]

Yea, that looks about right.

[FFY00]

Yes, exactly. That documentation will be the same for everyone, so better avoid duplicated efforts.

[pradyunsg]

We have this mostly, with https://packaging.python.org/en/latest/specifications/declaring-project-metadata/. This still needs examples though, so a PR for that would be welcome.