Document setuptools.build_meta

[pganssle]

There is currently no documentation for setuptools.build_meta!

We need to cover:

1. What it is - see this three part series for more background on python packaging and PEP 517
2. How to use it - you need to add a pyproject.toml to your source root with the following configuration (implementer - please confirm the right versions to pin):

[build-system]
requires = ["setuptools >= 40.6.0", "wheel"]
build-backend = "setuptools.build-meta"

3. How the semantics of a setuptools.build_meta differ from directly invoking setup.py; at the moment, the only deliberate difference is that with setuptools.build_meta, the source root is not on sys.path when you invoke it, meaning that you should either stop importing things from the local path, or add sys.path.insert(0, os.dirname(__file__)) to the top of your setup.py file.
4. The fact that, if you are a setup.cfg-only project, when using pyproject.toml setup.py is now optional!

We can cover setuptools.build_meta:__legacy__ in this ticket or in a separate one.

[ErikPohl-Lot49-Projects]

@pganssle Hello! I'd like to look into this one. Looks like a good challenge to take on!

[pganssle]

@ErikPohl-Lot49-Projects Sounds great! This is very important. I will be happy to review as soon as you have a draft.

[ErikPohl-Lot49-Projects]

@pganssle
Thanks! I'll let you know.

[ErikPohl-Lot49-Projects]

@pganssle
I'm going to find time Friday evening and this weekend to review the specifications. I'll let you know if I have questions!

[brettcannon]

I take it work on this has stalled? (I just tried to find the docs on PEP 517 support in setuptools and came up empty-handed and then found this issue.)

[brettcannon]

And a note in the docs that skipping setup.py prevents editable installs probably wouldn't go amiss.

[alvyjudy]

Hello! Just a trivial note, the build-backend in the pyroject.toml should be build_meta instead of build-meta otherwise an error will be thrown