Skip to content

docs: clarify where to run the "Compiling the test cases" commands - #6170

Open
zzbnb4396 wants to merge 1 commit into
pybind:masterfrom
zzbnb4396:docs/3871-basics-compile-context
Open

docs: clarify where to run the "Compiling the test cases" commands#6170
zzbnb4396 wants to merge 1 commit into
pybind:masterfrom
zzbnb4396:docs/3871-basics-compile-context

Conversation

@zzbnb4396

@zzbnb4396 zzbnb4396 commented Sep 3, 2026

Copy link
Copy Markdown

What

The First Steps page currently shows the "Compiling the test cases" commands
(mkdir build && cd build && cmake .. && make check) right after telling new
users they can install pybind11 via pip install, with no hint that the
commands are only meaningful from the root of a source checkout of the
pybind11 repository, nor that the pip wheels do not contain the bundled
tests.

This adds three sentences to docs/basics.rst clarifying that:

  • the commands must be run from the root of a source checkout of pybind11,
  • they compile and run the test suite bundled in the repository's tests/
    directory,
  • wheels installed via pip install pybind11 don't include those tests, so
    pip users should start from a git checkout instead (cross-linked to the
    installing page).

Why

Closes #3871. The reporter followed the page after a pip install and there
was no context about where to run the commands or where the test cases live;
the maintainer's reply in the thread invited exactly this kind of wording
(e.g. "starting with a git checkout").

How verified

  • docutils parse of docs/basics.rst: no structural errors, baseline vs.
    modified compared (only expected Sphinx-role noise).
  • git diff --check: clean.
  • No other sections or version numbers touched; this is a pure docs change.

Suggested changelog entry:

  • Docs: clarify that the "Compiling the test cases" commands on the First
    Steps page must be run from the root of a source checkout of pybind11,
    since pip wheels don't include the bundled test suite.

📚 Documentation preview 📚: https://pybind11--6170.org.readthedocs.build/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[BUG]: In the "First Steps", "Compiling the test cases" section of the documentation, there is no context as to where to run cmake.

1 participant