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

[cooperlees]

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.

[FFY00]

Hi, thank you for opening this issue. I am +0 on this, I wouldn't mind having the proposed documentation here, but another reasonable place would be https://github.com/pypa/packaging.python.org. To me, it is not clear which option is better, nothing particular really stands out here 😅

I would like to hear what other people think.

cc @pypa/packaging-user-guide-editors

[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.

[cooperlees]

All for de-duplication. If the main packaging user guide is where this should live, lets do it, My main goal here is I feel build's docs should link to that source of truth. Maybe we should create my suggestion / hybrid / part of it there and link to it from build'ss README + Docs.

As someone who's not involved in all this backend + frontend work (that is awesome and we need), I would love a source of truth to answer the two following questions for package creators and maintainers:

1. If I start a new project, what's the best way to set it up today
   1. e.g. I wanted to move bandersnatch (a pypa project) to use the latest hotness and has to ask you all to "do the best/right thing" - I'd like to help make docs point people like me in the right direction
2. What's the best practices I can do today so I am ready for where packaging is going/targeting

For years, setup.py, setup.cfg, pyproject.toml + other files for setuptools, poetry and pipenv have noted changes and plans but it's hard to know what package/modules owners should use and why/when. Also it's hard to know what to do to be as future proof too. Just trying to help here.

[henryiii]

The best answer I know of for those questions is https://scikit-hep.org/developer, though I'm biased as I wrote most of it. :)

I think python.packaing.org's tutorial is in pretty good shape, though pypa/packaging.python.org#1031 would be a huge step forward. And it should be clearly and nicely linked, yes!

[cooperlees]

The best answer I know of for those questions is https://scikit-hep.org/developer, though I'm biased as I wrote most of it. :)

I think python.packaing.org's tutorial is in pretty good shape, though pypa/packaging.python.org#1031 would be a huge step forward. And it should be clearly and nicely linked, yes!

Awesome - This is all the docs I couldn't find (and will be better once PR 1031 is landed). Would a PR adding a section linking to https://packaging.python.org/en/latest/tutorials/packaging-projects/ for making a project that could use build be accepted and a start here?

E.g.

Are you a Package Maintainer?

Want to know the latest way to setup your projects to use build? Visit the python.packaing.org's tutorial to get started.

[bhrutledge]

Great discussion here. I'm one of the PyPUG maintainers, and am particularly interested in making the packaging tutorial helpful. That said, its intended audience is folks who are completely new to packaging, i.e., not people who are looking for a general-purpose reference for how to set up a project. I don't know if such a thing exists, but that might be dependent on the choice of build backend. For example, it looks like the setuptools quickstart is pretty decent. I'd expect similar from Flit, PDM, Poetry, etc.

[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>.