From d457694ab0c935db02f4773aeb6ceed726aa905a Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Thu, 15 May 2025 12:03:32 -0400 Subject: [PATCH 1/7] docs: add a reference page for CLI utilities Signed-off-by: Henry Schreiner --- docs/about/changelog.md | 20 +++++++ docs/conf.py | 7 ++- docs/index.md | 1 + docs/reference/cli.md | 58 +++++++++++++++++++ pyproject.toml | 1 + src/scikit_build_core/build/__main__.py | 3 +- src/scikit_build_core/builder/wheel_tag.py | 6 +- .../file_api/_cattrs_converter.py | 5 +- src/scikit_build_core/file_api/query.py | 6 +- src/scikit_build_core/file_api/reply.py | 6 +- 10 files changed, 105 insertions(+), 8 deletions(-) create mode 100644 docs/reference/cli.md diff --git a/docs/about/changelog.md b/docs/about/changelog.md index 29475b06..1cefde52 100644 --- a/docs/about/changelog.md +++ b/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 diff --git a/docs/conf.py b/docs/conf.py index 23b35cef..8f662482 100644 --- 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. diff --git a/docs/index.md b/docs/index.md index 48ddea64..18b01094 100644 --- 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 new file mode 100644 index 00000000..59d76f95 --- /dev/null +++ b/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 + +``` diff --git a/pyproject.toml b/pyproject.toml index 924111bf..acf0f935 100644 --- 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 index b489e32f..9b42a16f 100644 --- 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 index 5d876948..e9216046 100644 --- 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="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 index 4abb6244..63a33b97 100644 --- 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 index 4c06e74d..0ec31a6d 100644 --- 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="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 index e10f2c7f..f5f63d77 100644 --- 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() From 6020be1c95169ac626999cd4db4e6471e810a9c7 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 15 May 2025 16:06:09 +0000 Subject: [PATCH 2/7] style: pre-commit fixes --- docs/about/changelog.md | 18 +++++++++--------- docs/reference/cli.md | 5 +++-- 2 files changed, 12 insertions(+), 11 deletions(-) diff --git a/docs/about/changelog.md b/docs/about/changelog.md index 1cefde52..9fb8625b 100644 --- a/docs/about/changelog.md +++ b/docs/about/changelog.md @@ -1,24 +1,24 @@ # Changelog - ## Version 0.11.3 Fixes: -* fix: add scripts to `_DICT_STR_FIELDS` for dynamic metadata. by @bilke in #1070 +- 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 +- 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 +- Generate config value reference by @LecrisUT in #1052 +- Update and fix projects list by @henryiii in #1075 ## Version 0.11.2 diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 59d76f95..bc3ab13b 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -1,6 +1,8 @@ # 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. +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 @@ -23,7 +25,6 @@ Example: ### Project table - ```{program-output} python -m scikit_build_core.build project-table --help ``` From 59bc343f46bff31d536a0c77acc5fa881564ece4 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Thu, 15 May 2025 12:07:49 -0400 Subject: [PATCH 3/7] docs: add self reference Signed-off-by: Henry Schreiner --- docs/about/changelog.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/about/changelog.md b/docs/about/changelog.md index 9fb8625b..ebd1262b 100644 --- a/docs/about/changelog.md +++ b/docs/about/changelog.md @@ -19,6 +19,7 @@ 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 From b96dc90823ba750134c674846468b251a3245c03 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Thu, 15 May 2025 12:18:43 -0400 Subject: [PATCH 4/7] Apply suggestions from code review --- src/scikit_build_core/builder/wheel_tag.py | 2 +- src/scikit_build_core/file_api/query.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/scikit_build_core/builder/wheel_tag.py b/src/scikit_build_core/builder/wheel_tag.py index e9216046..f07a5c1a 100644 --- a/src/scikit_build_core/builder/wheel_tag.py +++ b/src/scikit_build_core/builder/wheel_tag.py @@ -155,7 +155,7 @@ def as_tags_set(self) -> frozenset[packaging.tags.Tag]: from .._compat.argparse import ArgumentParser parser = ArgumentParser( - prog="scikit_build_core.builder.wheel_tag", + prog="python -m scikit_build_core.builder.wheel_tag", description="Get the computed wheel tag for the current environment.", allow_abbrev=False, ) diff --git a/src/scikit_build_core/file_api/query.py b/src/scikit_build_core/file_api/query.py index 0ec31a6d..6ce5c338 100644 --- a/src/scikit_build_core/file_api/query.py +++ b/src/scikit_build_core/file_api/query.py @@ -26,7 +26,7 @@ def stateless_query(build_dir: Path) -> Path: from .._compat.argparse import ArgumentParser parser = ArgumentParser( - prog="scikit_build_core.file_api.query", + prog="python -m scikit_build_core.file_api.query", allow_abbrev=False, description="Write a stateless query to a build directory", ) From efd66c5f6b68c76d21cb7e8eea357ee5d3645602 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Thu, 15 May 2025 23:00:23 -0400 Subject: [PATCH 5/7] ci: remove Windows from docs build (again) Signed-off-by: Henry Schreiner --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 36118b2b..6005e01f 100644 --- 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 From 3be2cfe877599522be268708b8e858464fa1433c Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 16 May 2025 03:00:55 +0000 Subject: [PATCH 6/7] style: pre-commit fixes --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6005e01f..904ebff4 100644 --- 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 command output issue (wrong Python selected) + runs-on: [ubuntu-latest, macos-latest] # Windows command output issue (wrong Python selected) steps: - uses: actions/checkout@v4 From 150b08c5b9b40a1c90ef629314432f59f57d256b Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Fri, 16 May 2025 00:09:26 -0400 Subject: [PATCH 7/7] docs: fix links and reduce checks Signed-off-by: Henry Schreiner --- README.md | 2 +- docs/about/projects.md | 4 ++-- docs/conf.py | 3 +++ docs/data/projects.toml | 2 +- 4 files changed, 7 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 30c48fc6..f4178ef9 100644 --- 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/projects.md b/docs/about/projects.md index 62a39707..a89670d5 100644 --- 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)) - + diff --git a/docs/conf.py b/docs/conf.py index 8f662482..e32012a0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -116,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 index 38d8a46d..f8a24579 100644 --- 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"