A unified pyproject.toml specification

[jeanas]

There are currently two specifications describing pyproject.toml, Declaring build system dependencies and Declaring project metadata. This split corresponds to history: first PEP 518 came, then PEP 621.

The two specifications are closely related (they define tables of the same file), and it's also slightly confusing to have the [tool] table defined in the "Declaring build system dependencies" spec. This PR proposes a unified spec.

Each commit is atomic so you can check that I didn't sneak in spec changes :)

---

📚 Documentation preview 📚: https://python-packaging-user-guide--1396.org.readthedocs.build/en/1396/

[willingc]

Nice merge of the 2 specs. I would suggest putting the note at the top to identify the history of the 2 PEPs.

[jeanas]

(Fixing the merge conflict with #1395.)

[jeanas]

Given that 2 people approved, is this ready to go? I'm asking because there is now #1414 building on top.

[jeanas]

Gentle ping? @willingc?

[pradyunsg]

IIUC, this is approved already and reviewed by multiple people -- trusting the group here and marking this into the queue without doing a review myself.

[jeanas]

Thank you @willingc, @sinoroc and @pradyunsg!

[jeanas]

@pradyunsg However, we need redirects in the RTD config to keep the old links working. (Sorry, I was sure I had mentioned this in the PR description.) Namely, from /specifications/declaring-build-dependencies/ and /specifications/declaring-project-metadata/ to /specifications/pyproject-toml/.

Also, I'm puzzled because I thought the GitHub merge queue was supposed to check the merged result, but CI passed on this PR even though it conflicts with some of @sinoroc's work on main that adds references to labels that I renamed 😠 I'm going to prepare a PR to fix that right now and then investigate why the CI didn't work as I thought...

[hugovk]

See also #1434, would it be okay to keep the declaring-project-metadata reference?

We're relying on it to build PEP 621 in the PEPs repo via intersphinx. And/or we can fix PEP 621 to use the new ref.

But it might be worth keeping the old refs to avoid breaking intersphinx for other people/avoid linkrot. (We usually do this in https://github.com/python/devguide.)

[jeanas]

Some updates here:

@pradyunsg However, we need redirects in the RTD config to keep the old links working. (Sorry, I was sure I had mentioned this in the PR description.) Namely, from /specifications/declaring-build-dependencies/ and /specifications/declaring-project-metadata/ to /specifications/pyproject-toml/.

Opened #1437.

Also, I'm puzzled because I thought the GitHub merge queue was supposed to check the merged result, but CI passed on this PR even though it conflicts with some of @sinoroc's work on main that adds references to labels that I renamed 😠 I'm going to prepare a PR to fix that right now and then investigate why the CI didn't work as I thought...

I've figured that out­ — it's pretty nasty. See #1438.

See also #1434, would it be okay to keep the declaring-project-metadata reference?

This is being discussed in #1434.