docs: add a reference page for CLI utilities (#1080)

henryiii · pre-commit-ci[bot] · web-flow · commit 813962094564 · 2025-05-16T00:38:57.000-04:00
Adding a reference page for this.

There's also a `pathlib._local.Path` warning when building the docs we
should try to fix eventually.

Also preparing for a patch release with the 3.14 support and a bug fix.

---------

Signed-off-by: Henry Schreiner &lt;henryschreineriii@gmail.com&gt;
Co-authored-by: pre-commit-ci[bot] &lt;66853113+pre-commit-ci[bot]@users.noreply.github.com&gt;
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -340,7 +340,7 @@ jobs:
     timeout-minutes: 25
     strategy:
       matrix:
-        runs-on: [ubuntu-latest, macos-latest, windows-latest]
+        runs-on: [ubuntu-latest, macos-latest] # Windows command output issue (wrong Python selected)
 
     steps:
       - uses: actions/checkout@v4
diff --git a/README.md b/README.md
@@ -395,7 +395,7 @@ Science Foundation.
 [github-discussions-link]:  https://github.com/orgs/scikit-build/discussions
 [hatchling]:                https://hatch.pypa.io/latest
 [maturin]:                  https://www.maturin.rs
-[meson-python]:             https://meson-python.readthedocs.io
+[meson-python]:             https://mesonbuild.com/meson-python
 [py-build-cmake]:           https://tttapa.github.io/py-build-cmake
 [pypi-link]:                https://pypi.org/project/scikit-build-core/
 [pypi-platforms]:           https://img.shields.io/pypi/pyversions/scikit-build-core
diff --git a/docs/about/changelog.md b/docs/about/changelog.md
@@ -1,5 +1,26 @@
 # 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
+- Document CLI utilities by @henryiii in #1080
+
 ## Version 0.11.2
 
 This release allows dynamic-metadata to reference other fields, which enables a
diff --git a/docs/about/projects.md b/docs/about/projects.md
@@ -63,14 +63,14 @@ for project in projects["project"]:
 * [gemmi](https://pypi.org/project/gemmi) ([source](https://github.com/project-gemmi/gemmi/blob/HEAD/pyproject.toml))
 * [gdstk](https://pypi.org/project/gdstk) ([source](https://github.com/heitzmann/gdstk/blob/HEAD/pyproject.toml))
 * [symusic](https://pypi.org/project/symusic) ([source](https://github.com/Yikai-Liao/symusic/blob/HEAD/pyproject.toml))
-* [s5cmd](https://pypi.org/project/s5cmd) ([source](https://github.com/jcfr/s5cmd-python-distributions/blob/HEAD/pyproject.toml))
+* [s5cmd](https://pypi.org/project/s5cmd) ([source](https://github.com/ImagingDataCommons/s5cmd-python-distributions/blob/HEAD/pyproject.toml))
 * [pyslang](https://pypi.org/project/pyslang) ([source](https://github.com/MikePopoloski/slang/blob/HEAD/pyproject.toml))
 * [librapid](https://pypi.org/project/librapid) ([source](https://github.com/LibRapid/librapid/blob/HEAD/pyproject.toml))
 * [pyresidfp](https://pypi.org/project/pyresidfp) ([source](https://github.com/pyresidfp/pyresidfp/blob/HEAD/pyproject.toml))
 * [kiss-icp](https://pypi.org/project/kiss-icp) ([source](https://github.com/PRBonn/kiss-icp/blob/HEAD/python/pyproject.toml))
 * [simsopt](https://pypi.org/project/simsopt) ([source](https://github.com/hiddenSymmetries/simsopt/blob/HEAD/pyproject.toml))
 * [mqt-core](https://pypi.org/project/mqt-core) ([source](https://github.com/munich-quantum-toolkit/core/blob/HEAD/pyproject.toml))
-<!--[[[end]]] (checksum: 02f85758156e39de6e127e2b5ce0f9bc)-->
+<!--[[[end]]] (checksum: a798ae9bb220ab16cfe9402431cde0cf)-->
 
 <!-- prettier-ignore-end -->
 
diff --git a/docs/conf.py b/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.
@@ -115,6 +116,9 @@
     "default-versioning-scheme",
     "git-archives",
 ]
+linkcheck_ignore = [
+    r"https://github.com/search\?.*",
+]
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
diff --git a/docs/data/projects.toml b/docs/data/projects.toml
@@ -114,7 +114,7 @@ github = "Yikai-Liao/symusic"
 
 [[project]]
 pypi = "s5cmd"
-github = "jcfr/s5cmd-python-distributions"
+github = "ImagingDataCommons/s5cmd-python-distributions"
 
 [[project]]
 pypi = "pyslang"
diff --git a/docs/index.md b/docs/index.md
@@ -74,6 +74,7 @@ about/changelog
 api/scikit_build_core
 schema
 reference/configs
+reference/cli
 ```
 
 ## Indices and tables
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
@@ -0,0 +1,59 @@
+# 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
+
+```
diff --git a/pyproject.toml b/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"',
diff --git a/src/scikit_build_core/build/__main__.py b/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")
diff --git a/src/scikit_build_core/builder/wheel_tag.py b/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="python -m scikit_build_core.builder.wheel_tag",
+        description="Get the computed wheel tag for the current environment.",
+        allow_abbrev=False,
+    )
     parser.add_argument(
         "--archs",
         nargs="*",
diff --git a/src/scikit_build_core/file_api/_cattrs_converter.py b/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()
 
diff --git a/src/scikit_build_core/file_api/query.py b/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="python -m 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()
 
diff --git a/src/scikit_build_core/file_api/reply.py b/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()
 

Original file line number	Diff line number	Diff line change
`@@ -101,6 +101,7 @@ docs = [`
`101`	`101`	`"sphinx-inline-tabs",`
`102`	`102`	`"sphinx-jsonschema",`
`103`	`103`	`"sphinx-tippy",`
	`104`	`+ "sphinxcontrib-programoutput",`
`104`	`105`	`]`
`105`	`106`	`wheel-free-setuptools = [`
`106`	`107`	`'setuptools>=70.1; python_version>="3.8"',`
Original file line number	Diff line number	Diff line change
`@@ -50,8 +50,9 @@ def get_requires(mode: Literal["sdist", "wheel", "editable"]) -> None:`
`50`	`50`
`51`	`51`	`def main() -> None:`
`52`	`52`	`parser = ArgumentParser(`
	`53`	`+ prog="python -m scikit_build_core.build",`
`53`	`54`	`allow_abbrev=False,`
`54`		`- description="Build backend utilities",`
	`55`	`+ description="Build backend utilities.",`
`55`	`56`	`)`
`56`	`57`
`57`	`58`	`subparsers = parser.add_subparsers(help="Commands")`