docs: drop the invented --srcdir option from the basic-usage how-to

[hxperl]

Description

docs/how-to/basic-usage.rst tells the reader that the positional source directory has an explicit option form:

Build defaults to the current directory. To build from a different location:

$ python -m build path/to/project

Or explicitly:

$ python -m build --srcdir path/to/project

There is no --srcdir option. srcdir is the parser's only positional argument (__main__.py:541, nargs='?') and it has no long-option alias, so the second command does not run:

$ python -m build --srcdir path/to/project
usage: python -m build [-h] [--version] [--quiet | --verbose] [--outdir PATH]
                       [--sdist-extract-dir PATH] [--sdist] [--wheel]
                       [--metadata] [--report PATH]
                       [--config-setting KEY=[VALUE] |
                       --config-json JSON_STRING] [--installer {pip,uv} |
                       --no-isolation] [--env-dir PATH]
                       [--dependency-constraints-txt PATH]
                       [--skip-dependency-check]
                       [srcdir]
python -m build: error: unrecognized arguments: --srcdir
$ echo $?
2

(run against main at 65b46ef)

This is not a flag that was renamed or removed. git log -S '--srcdir' finds the string in exactly one commit — a77870d, the Diátaxis reorganization (#988) that wrote this page — and never in src/.

I checked the rest of the docs the same way, by pulling every python -m build / pyproject-build command line out of docs/ and README.md and validating each flag against the parser. The only other unrecognized strings are -C--build-option=--build-number=123 and -C=--my-setting (backend config-setting values, correct as written) and uvx --from build ... (a uvx flag). So this is the only occurrence.

The change

I removed the "Or explicitly" block and replaced it with a sentence saying the source directory is positional.

The judgement call: the other way to make the page true is to add a --srcdir alias to the parser, which would also spare anyone who has already copied the documented command. I did not do that because it is a new option rather than a docs fix, and it is your call whether build wants one. Happy to switch if you would rather keep the documented spelling working.

What I verified

• The reproduction above, against unmodified main, before touching anything.
• sphinx-build -W -n -b html docs and proselint check docs — the two commands in [env.docs] — both succeed before and after the change.
• pytest tests -n 4: 3 failed, 296 passed, 49 skipped. The three failures are an artefact of my own setup, not this change: I ran from PYTHONPATH=src without installing the package, so the subprocesses those tests spawn fail with ModuleNotFoundError: No module named 'build'. This PR touches one .rst file and no code.
• macOS arm64, Python 3.14.4. I did not run the suite on Linux or other Python versions, or the integration tests; CI will need to cover those.

I have not added the changelog fragment yet because the filename needs this PR's number — I will push docs/changelog/<n>.doc.rst as soon as the number exists.

Checklist

• Documentation builds (sphinx-build -W -n, proselint)
• Tests pass locally, with the caveat noted above
• Changelog fragment — to follow, needs the PR number

---

Disclosure: this was found and drafted with AI assistance (Claude Code). The reproduction, the docs build, the test run and the git log -S history check are real runs on my machine, and I reviewed the change before opening this.

[hxperl]

Added the changelog fragment as docs/changelog/1186.doc.rst.

[henryiii]

I think we can remove this line too, as long as we don't indicate it that it's optional, I don't think we need to state it.