Add "Quickstart" + "Move from setup.py" section to build's docs

Howdy,

I decided to catch up on the PyPA packaging world on all my projects today and feel there is room for a section in build’s docs to describe the ways to start a new project and/or move from traditional setup.py project to a build project.

If this is not the goal of builds docs and it’s somewhere else, how can we make it easier to find? It’s very hard to find and answer “How should I build a new Python prokject in 2022” … I know there is lots of legacy etc. here but making this easier to find and link to should help new projects adopt these things. I did see pip makes mention from googling

I also got recommendations that are not mention in the docs (unless I’m blind which there is a chance). My example here was adding a section to pyproject.toml - So I feel we should mention that somewhere. My suggestion was:

[build-system]
# setuptools 43 includes pyproject.toml
requires = ["setuptools>=43"]
build-backend = "setuptools.build_meta"

• I guess we could link to pip: https://pip.pypa.io/en/stable/reference/build-system/pyproject-toml/

Suggested Overview

(I will update as discussion suggests etc.)

• Quickstart:
  • Create a setup.cfg (link to https://setuptools.pypa.io/en/latest/userguide/declarative_config.html)
    • Give a small example
    • Note that setup.py is supported today but is deprecated
  • Get build installed into your [virtual] environment
    • Remove build dependencies from you CI / main environment due to builds dedicated venv creation
  • Create a pyproject.toml
    • Show minimum example toml file
    • Link to detail explanation of the toml options for build: https://pip.pypa.io/en/stable/reference/build-system/pyproject-toml/
  • How to test build succeeded
    • python -m build
    • See a sdist + wheel
    • Install in a venv
• Extra:
  • Maybe add a flow diagram of build’s process

(Totally up for reasoning - Thus the issue before the PR)

Side Questions

• Is the metadata in setup.py’s long term goal to be in setup.cfg?

Please lets focus on the quick start and open other issues for other docs enhancements that come from this discussion, if they do.

[henryiii]

I’d rather have (better?) links to packaging.python.org, I don’t think we need to explain how to set up a package. Some updates could be made there (I’ve been really hoping for a PEP 621 update, but that’s waiting on setuptools, which is happening at some point). Those docs could take some of the ideas, though - I’d really like to see better pipx run usage, personally, which skips most of the messy environment handling.

If we have the same docs in many places, we have to maintain more, versions go out of date, etc. Build is not tied to a specific backend, either - maybe link to some popular backend docs (setuptools, flit)?

A few notes:

setup.py is not deprecated. It’s the only way to do non-metadata related tasks, like setting up extension compiling, etc. It’s just recommended to statically define metadata. And I believe setup.cfg will be deprecated for pyproject.toml & PEP 621 config (very long term, but happening in a PR now).

[build-system]
requires = ["setuptools>=42", "wheel"]
build-backend = "setuptools.build_meta"

is a minimum pyproject.toml. Though I’d probably recommend flit & PEP 621 config over setup tools for non-compiled projects.

[layday]

How about:

build is a standards-based tool for generating Python package distributions. If you have a setuptools project and would like to start using build, create a pyproject.toml with: <snip>. If you are interested in exploring alternative backends which can be used with build, see <scikit-hep/cookie>. If you are new to Python packaging, see <PUG guide>.