Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a dedicated "Build system interface" reference section #10497

Merged
merged 6 commits into from
Sep 30, 2021

Conversation

pradyunsg
Copy link
Member

This reworks a substantial portion of our existing build system related
documentation, putting it all in a single location.

There are certain areas that have been rephrased or rewritten:

  • The setup.py interface is now considered an implementation detail.
  • The setup.py interface is explicitly noted as a legacy interface, due
    for removal.
  • The pyproject.toml interface now has clearer documentation on how it
    is used and how it operates.
  • Clearer separation of --use-pep-517 and --no-build-isolation, to
    make the difference between the two clearer.

@pradyunsg pradyunsg added the type: docs Documentation related label Sep 22, 2021
@pradyunsg
Copy link
Member Author

Toward #9475.

@pradyunsg
Copy link
Member Author

pradyunsg commented Sep 22, 2021

@pypa/pip-committers I'd really like for someone to take a proper look at this PR -- it's a decently large change, and very much worthwhile IMO. However, it is also one of the places where we should get the nuances and phrasing right and to be something that we're comfortable with.

Here's the link to the preview: https://pip--10497.org.readthedocs.build/en/10497/ -- you'll wanna look under Reference. :)

@pradyunsg pradyunsg force-pushed the docs/build-system-reference branch from c34a091 to 265f138 Compare September 22, 2021 06:05
@pradyunsg pradyunsg added this to the 21.3 milestone Sep 22, 2021
Copy link
Member

@pfmoore pfmoore left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall, this looks good. I've added a bunch of comments, but they are mainly just clarifications of things I think are a bit unclear, and one or two nitpicks.

The most substantial query is around the setup_requires explanation, which I think might have some inaccuracies.

docs/html/reference/build-system/index.md Outdated Show resolved Hide resolved
docs/html/reference/build-system/index.md Outdated Show resolved Hide resolved
docs/html/reference/build-system/index.md Outdated Show resolved Hide resolved
docs/html/reference/build-system/index.md Outdated Show resolved Hide resolved
docs/html/reference/build-system/index.md Show resolved Hide resolved
docs/html/reference/build-system/pyproject-toml.md Outdated Show resolved Hide resolved
docs/html/reference/build-system/pyproject-toml.md Outdated Show resolved Hide resolved
docs/html/reference/build-system/pyproject-toml.md Outdated Show resolved Hide resolved
docs/html/reference/build-system/setup-py.md Outdated Show resolved Hide resolved
@pradyunsg pradyunsg mentioned this pull request Sep 24, 2021
13 tasks
pradyunsg and others added 4 commits September 28, 2021 21:10
This reworks a substantial portion of our existing build system related
documentation, putting it all in a single location.

There are certain areas that have been rephrased or rewritten:

- The setup.py interface is now considered an implementation detail.
- The setup.py interface is explicitly noted as a legacy interface, due
  for removal.
- The pyproject.toml interface now has clearer documentation on how it
  is used and how it operates.
- Clearer separation of `--use-pep-517` and `--no-build-isolation`, to
  make the difference between the two clearer.
Co-authored-by: Paul Moore <p.f.moore@gmail.com>
@pradyunsg pradyunsg force-pushed the docs/build-system-reference branch from 265f138 to 25a31d4 Compare September 29, 2021 18:57
It wasn't clear what "those dependencies" refers to.
@pradyunsg
Copy link
Member Author

pradyunsg commented Sep 29, 2021

@pfmoore That should be all the feedback addressed! I'd like you to take a look at the easy_install/setup_requires thing again, since that's the only bit where I've had done significant stuff.

PS: I added you as a co-author on one of the commits, since a lot of the stuff in it is based on copy-pasting what you've suggested. :)

Copy link
Member

@pfmoore pfmoore left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. One spelling nit is all.

docs/html/reference/build-system/index.md Outdated Show resolved Hide resolved
Co-authored-by: Paul Moore <p.f.moore@gmail.com>
@pradyunsg pradyunsg merged commit 989ec21 into pypa:main Sep 30, 2021
@pradyunsg pradyunsg deleted the docs/build-system-reference branch September 30, 2021 06:09
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Oct 15, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
type: docs Documentation related
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants