Add pytest-cmake CLI and remove deprecated CMake module integration docs

- Added pytest-cmake command-line tool with --cmake-dir to print the CMake
  config path, simplifying integration for virtualenvs, non-standard installs,
  and --user installs.
- Updated documentation to recommend using the CLI instead of manually setting
  CMAKE_PREFIX_PATH.
- Removed documentation for integrating the CMake module directly from the Git
  repository, as this unsustainable method was already discouraged.
- Updated packaging configuration to include CLI entry point and adjust
  included files.

Author: buddly27

doc/integration.rst

@@ -42,17 +42,12 @@ able to discover the newly installed configuration automatically using its
     <https://cmake.org/cmake/help/latest/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.html>`_
     option should not be set to False.
 
-When using a Python virtual environment, or if Python is installed in a
-non-standard location, the :envvar:`CMAKE_PREFIX_PATH` environment variable
-(or :term:`CMake` option) can be used to guide the discovery process::
+When using a Python virtual environment, installing Python in a non-standard location, or
+installing ``pytest-cmake`` in the `Python user directory
+<https://pip.pypa.io/en/stable/cli/pip_install/#install-user>`_, specify the ``Pytest_ROOT``
+path via the CLI::
 
-    cmake -S . -B ./build -D "CMAKE_PREFIX_PATH=/path/to/python/prefix"
-
-This is also necessary when installing the configuration in the
-`Python user directory
-<https://pip.pypa.io/en/stable/cli/pip_install/#install-user>`_::
-
-    pip install pytest-cmake --user
+    cmake -S . -B ./build -D "Pytest_ROOT=$(python -m pytest_cmake --cmake-dir)"
 
 .. _integration/config/example:
 
@@ -65,41 +60,10 @@ Ensure that :term:`nanobind` is available, and install :term:`Pytest` with its
 :term:`CMake` configuration as described in the :ref:`previous section <installing>`.
 Then build the example::
 
-    export nanobind_ROOT=$(python -m nanobind --cmake_dir)
-    cmake -S ./example -B ./build
+    cmake -S ./example -B ./build -D "nanobind_ROOT=$(python -m nanobind --cmake-dir)"
     cmake --build ./build
 
 Finally, run the tests as follows::
 
     ctest --test-dir ./build -VV
 
-.. _integration/module:
-
-Finding Module
-==============
-
-The package integration within a :term:`CMake` project can also be done using
-the :file:`FindPytest.cmake` module. The CMake files can be copied into a
-new project, or the following code can be added before invoking the
-:term:`find_package` function:
-
-.. code-block:: cmake
-
-    set(pytest_url https://github.com/python-cmake/pytest-cmake/archive/main.zip)
-
-    # Fetch CMake files from the main branch of the Github repository
-    file(DOWNLOAD ${pytest_url} ${CMAKE_BINARY_DIR}/pytest.zip)
-    file(
-        ARCHIVE_EXTRACT INPUT ${CMAKE_BINARY_DIR}/pytest.zip
-        DESTINATION ${CMAKE_BINARY_DIR}
-        PATTERNS "*.cmake"
-    )
-
-    # Expand the module path variable to discover the `FindPytest.cmake` module.
-    set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} ${CMAKE_BINARY_DIR}/pytest-cmake-main/cmake)
-
-.. warning::
-
-    It is strongly recommended to use the :term:`Pip` installation over
-    this method.
-

doc/release/release_notes.rst

@@ -4,6 +4,21 @@
 Release Notes
 *************
 
+.. release:: Upcoming
+
+    .. change:: new
+
+        Added ``pytest-cmake`` CLI with ``--cmake-dir`` to print the
+        :term:`CMake` config path, simplifying integration with virtualenvs,
+        non-standard installs, or `--user
+        <https://pip.pypa.io/en/stable/cli/pip_install/#install-user>`_ installs.
+
+    .. change:: changed
+
+        Removed documentation for integrating the :term:`CMake` module directly
+        from the Git repository, as this unsustainable method was already
+        discouraged.
+
 .. release:: 1.0.0
     :date: 2025-08-13
 

pyproject.toml

@@ -33,6 +33,9 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 
+[project.scripts]
+pytest-cmake = "pytest_cmake.__main__:main"
+
 [project.urls]
 Documentation = "https://python-cmake.github.io/pytest-cmake"
 Repository = "https://github.com/python-cmake/pytest-cmake"
@@ -50,7 +53,8 @@ path = "build_config.py"
 "cmake/PytestAddTests.cmake" = "share/Pytest/cmake/PytestAddTests.cmake"
 
 [tool.hatch.build.targets.wheel]
-only-include = ["*.cmake"]
+packages = ["src/pytest_cmake"]
+only-include = ["src/pytest_cmake", "*.cmake"]
 
 [tool.hatch.build.targets.sdist]
-only-include = ["cmake", "build_config.py"]
+only-include = ["src/pytest_cmake", "cmake", "build_config.py"]

src/pytest_cmake/__init__.py

@@ -0,0 +1,29 @@
+import argparse
+from pathlib import Path
+import sys
+import sysconfig
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="pytest-cmake",
+        description="Utility commands for pytest-cmake packaging.",
+    )
+    parser.add_argument(
+        "--cmake_dir", "--cmake-dir",
+        action="store_true",
+        help="Print the CMake config directory path and exit.",
+    )
+    args = parser.parse_args(argv)
+
+    if args.cmake_dir:
+        data_root = Path(sysconfig.get_path("data"))
+        print(data_root / "share" / "Pytest" / "cmake")
+        return 0
+
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())