Added documentation for build_meta

[alvyjudy]

#1698 Summary of changes

Added documentation for build_meta. It is not fully completed but with enough content to get started with the module. (This is my first time contributing and I'm trying my best to follow the guidelines and beginner docs, hopefully I didn't miss anything:)

I have made the simplification that it is a setup.cfg only package. But I can definitely change this later!

Pull Request Checklist

• Changes have tests
• News fragment added in changelog.d. See documentation for details

[jaraco]

Looks good to me. Thanks for the contrib.

[jaraco]

I was about to accept this change when I realize there are two major issues:

• This new document isn't linked from anywhere else in the documentation.
• The main documentation still recommends setup() for building a package.

What we really want is to present the simplest, best practices first, not tell the wrong story, then give a sordid history, then tell the right story.

For now, I'm going to accept these changes as they are, but we'll want to iterate on them to integrate them into the documentation as first-class behaviors.

[alvyjudy]

Hi, thanks for accepting the PR! I'm just a little confused because I thought this documentation was to explain how to use the functions provided in build_meta.py but that doesn't seem like the case now? Is there something I have overlooked?

[jaraco]

Hi alvyjudy. Indeed, the fact that setuptools exposes its PEP 517 build functionality through a module named setuptools.build_meta is an implementation detail that's only pertinent to packages that wish to declare that backend as the backend. I would discourage (and definitely not document) the use of that module explicitly... which is why I'd like to incorporate your documentation, which is helpful, into the best recommendation (which is to declare setuptools.build_meta as the build-backend, and build using pep517 (or a better tool if it should come along).