docs: add a reference page for CLI utilities

Signed-off-by: Henry Schreiner <[email protected]>

Author: henryiii

docs/about/changelog.md

@@ -1,5 +1,25 @@
 # Changelog
 
+
+## Version 0.11.3
+
+Fixes:
+
+* fix: add scripts to `_DICT_STR_FIELDS` for dynamic metadata. by @bilke in #1070
+
+CI and testing:
+
+* Officially support Python 3.14, color help @henryiii in #1074
+* Remove no-wheel based on virtualenv version by @henryiii in #1071
+* Work when `CMAKE_GENERATOR` is set by @henryiii in #1066
+* Try a workaround for packit `propose-downstream` by @LecrisUT in #1067
+* Update coverage a bit by @henryiii in #1073
+
+Documentation:
+
+* Generate config value reference by @LecrisUT in #1052
+* Update and fix projects list by @henryiii in #1075
+
 ## Version 0.11.2
 
 This release allows dynamic-metadata to reference other fields, which enables a

docs/conf.py

@@ -56,18 +56,19 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "conftabs",
     "myst_parser",
+    "sphinx-jsonschema",
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     "sphinx.ext.linkcode",
     "sphinx.ext.mathjax",
     "sphinx.ext.napoleon",
+    "sphinx_autodoc_typehints",
     "sphinx_copybutton",
     "sphinx_inline_tabs",
-    "sphinx_autodoc_typehints",
-    "conftabs",
-    "sphinx-jsonschema",
     "sphinx_tippy",
+    "sphinxcontrib.programoutput",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/index.md

@@ -74,6 +74,7 @@ about/changelog
 api/scikit_build_core
 schema
 reference/configs
+reference/cli
 ```
 
 ## Indices and tables

docs/reference/cli.md

@@ -0,0 +1,58 @@
+# CLI Reference
+
+Scikit-build-core has a few integrated CLI tools. These are not guaranteed to be stable between releases yet, but can still be useful to investigate your environment.
+
+## Build utilities
+
+```{program-output} python -m scikit_build_core.build --help
+
+```
+
+### Build requirements
+
+```{program-output} python -m scikit_build_core.build requires --help
+
+```
+
+Example:
+
+```{command-output} python -m scikit_build_core.build requires
+:cwd: ../examples/getting_started/c
+
+```
+
+### Project table
+
+
+```{program-output} python -m scikit_build_core.build project-table --help
+
+```
+
+Example:
+
+```{command-output} python -m scikit_build_core.build project-table
+:cwd: ../examples/getting_started/c
+
+```
+
+## Wheel tag
+
+```{program-output} python -m scikit_build_core.builder.wheel_tag --help
+
+```
+
+Example:
+
+```{command-output} python -m scikit_build_core.builder.wheel_tag
+
+```
+
+## File API tools
+
+```{program-output} python -m scikit_build_core.file_api.query --help
+
+```
+
+```{program-output} python -m scikit_build_core.file_api.reply --help
+
+```

pyproject.toml

@@ -101,6 +101,7 @@ docs = [
     "sphinx-inline-tabs",
     "sphinx-jsonschema",
     "sphinx-tippy",
+    "sphinxcontrib-programoutput",
 ]
 wheel-free-setuptools = [
     'setuptools>=70.1; python_version>="3.8"',

src/scikit_build_core/build/__main__.py

@@ -50,8 +50,9 @@ def get_requires(mode: Literal["sdist", "wheel", "editable"]) -> None:
 
 def main() -> None:
     parser = ArgumentParser(
+        prog="python -m scikit_build_core.build",
         allow_abbrev=False,
-        description="Build backend utilities",
+        description="Build backend utilities.",
     )
 
     subparsers = parser.add_subparsers(help="Commands")

src/scikit_build_core/builder/wheel_tag.py

@@ -154,7 +154,11 @@ def as_tags_set(self) -> frozenset[packaging.tags.Tag]:
 if __name__ == "__main__":
     from .._compat.argparse import ArgumentParser
 
-    parser = ArgumentParser(allow_abbrev=False)
+    parser = ArgumentParser(
+        prog="scikit_build_core.builder.wheel_tag",
+        description="Get the computed wheel tag for the current environment.",
+        allow_abbrev=False,
+    )
     parser.add_argument(
         "--archs",
         nargs="*",

src/scikit_build_core/file_api/_cattrs_converter.py

@@ -69,7 +69,10 @@ def load_reply_dir(reply_dir: Path) -> Index:
     except ModuleNotFoundError:
         rich_print = builtins.print
 
-    parser = ArgumentParser(allow_abbrev=False)
+    parser = ArgumentParser(
+        allow_abbrev=False,
+        description="This runs cattrs (required) instead of the built-in converter, for comparison.",
+    )
     parser.add_argument("reply_dir", type=Path, help="Path to the reply directory")
     args = parser.parse_args()
 

src/scikit_build_core/file_api/query.py

@@ -25,7 +25,11 @@ def stateless_query(build_dir: Path) -> Path:
 if __name__ == "__main__":
     from .._compat.argparse import ArgumentParser
 
-    parser = ArgumentParser(allow_abbrev=False)
+    parser = ArgumentParser(
+        prog="scikit_build_core.file_api.query",
+        allow_abbrev=False,
+        description="Write a stateless query to a build directory",
+    )
     parser.add_argument("build_dir", type=Path, help="Path to the build directory")
     args = parser.parse_args()
 

src/scikit_build_core/file_api/reply.py

@@ -119,7 +119,11 @@ def load_reply_dir(path: Path) -> Index:
     except ModuleNotFoundError:
         rich_print = builtins.print
 
-    parser = ArgumentParser(allow_abbrev=False)
+    parser = ArgumentParser(
+        prog="python -m scikit_build_core.file_api.reply",
+        allow_abbrev=False,
+        description="Read a query written out to a build directory.",
+    )
     parser.add_argument("reply_dir", type=Path, help="Path to the reply directory")
     args = parser.parse_args()