Generate config reference

LecrisUT · LecrisUT · commit b07e09896933 · 2025-04-23T18:16:13.000+02:00
Signed-off-by: Cristian Le &lt;git@lecris.dev&gt;
diff --git a/docs/index.md b/docs/index.md
@@ -73,6 +73,7 @@ about/changelog
 
 api/scikit_build_core
 schema
+reference/configs
 ```
 
 ## Indices and tables
diff --git a/docs/reference/configs.rst b/docs/reference/configs.rst
@@ -0,0 +1,264 @@
+Configurations
+==============
+
+.. confval:: cmake.minimum-version
+  :type: ``Version``
+
+  DEPRECATED in 0.8; use version instead.
+
+.. confval:: cmake.version
+  :type: ``SpecifierSet``
+
+  The versions of CMake to allow. If CMake is not present on the system or does not pass this specifier, it will be downloaded via PyPI if possible. An empty string will disable this check. The default on 0.10+ is "CMakeLists.txt", which will read it from the project's CMakeLists.txt file, or ">=3.15" if unreadable or <0.10.
+
+.. confval:: cmake.args
+  :type: ``list[str]``
+
+  A list of args to pass to CMake when configuring the project. Setting this in config or envvar will override toml. See also ``cmake.define``.
+
+.. confval:: cmake.define
+  :type: ``EnvVar``
+
+  A table of defines to pass to CMake when configuring the project. Additive.
+
+.. confval:: cmake.verbose
+  :type: ``bool``
+
+  DEPRECATED in 0.10, use build.verbose instead.
+
+.. confval:: cmake.build-type
+  :type: ``str``
+  :default: "Release"
+
+  The build type to use when building the project. Valid options are: "Debug", "Release", "RelWithDebInfo", "MinSizeRel", "", etc.
+
+.. confval:: cmake.source-dir
+  :type: ``Path``
+  :default: "."
+
+  The source directory to use when building the project. Currently only affects the native builder (not the setuptools plugin).
+
+.. confval:: cmake.targets
+  :type: ``list[str]``
+
+  DEPRECATED in 0.10; use build.targets instead.
+
+.. confval:: ninja.minimum-version
+  :type: ``Version``
+
+  DEPRECATED in 0.8; use version instead.
+
+.. confval:: ninja.version
+  :type: ``SpecifierSet``
+  :default: ">=1.5"
+
+  The versions of Ninja to allow. If Ninja is not present on the system or does not pass this specifier, it will be downloaded via PyPI if possible. An empty string will disable this check.
+
+.. confval:: ninja.make-fallback
+  :type: ``bool``
+  :default: true
+
+  If Ninja is not present on the system or is older than required, it will be downloaded via PyPI if this is false.
+
+.. confval:: logging.level
+  :type: ``"NOTSET" | "DEBUG" | "INFO" | "WARNING" | "ERROR" | "CRITICAL"``
+  :default: "WARNING"
+
+  The logging level to display, "DEBUG", "INFO", "WARNING", and "ERROR" are possible options.
+
+.. confval:: sdist.include
+  :type: ``list[str]``
+
+  Files to include in the SDist even if they are skipped by default. Supports gitignore syntax.
+
+.. confval:: sdist.exclude
+  :type: ``list[str]``
+
+  Files to exclude from the SDist even if they are included by default. Supports gitignore syntax.
+
+.. confval:: sdist.reproducible
+  :type: ``bool``
+  :default: true
+
+  If set to True, try to build a reproducible distribution (Unix and Python 3.9+ recommended).  ``SOURCE_DATE_EPOCH`` will be used for timestamps, or a fixed value if not set.
+
+.. confval:: sdist.cmake
+  :type: ``bool``
+  :default: false
+
+  If set to True, CMake will be run before building the SDist.
+
+.. confval:: wheel.packages
+  :type: ``list[str]``
+  :default: ["src/<package>", "python/<package>", "<package>"]
+
+  A list of packages to auto-copy into the wheel. If this is not set, it will default to the first of ``src/<package>``, ``python/<package>``, or ``<package>`` if they exist.  The prefix(s) will be stripped from the package name inside the wheel. If a dict, provides a mapping of package name to source directory.
+
+.. confval:: wheel.py-api
+  :type: ``str``
+
+  The Python tags. The default (empty string) will use the default Python version. You can also set this to "cp38" to enable the CPython 3.8+ Stable ABI / Limited API (only on CPython and if the version is sufficient, otherwise this has no effect). Or you can set it to "py3" or "py2.py3" to ignore Python ABI compatibility. The ABI tag is inferred from this tag.
+
+.. confval:: wheel.expand-macos-universal-tags
+  :type: ``bool``
+  :default: false
+
+  Fill out extra tags that are not required. This adds "x86_64" and "arm64" to the list of platforms when "universal2" is used, which helps older Pip's (before 21.0.1) find the correct wheel.
+
+.. confval:: wheel.install-dir
+  :type: ``str``
+
+  The install directory for the wheel. This is relative to the platlib root. You might set this to the package name. The original dir is still at SKBUILD_PLATLIB_DIR (also SKBUILD_DATA_DIR, etc. are available). EXPERIMENTAL: An absolute path will be one level higher than the platlib root, giving access to "/platlib", "/data", "/headers", and "/scripts".
+
+.. confval:: wheel.license-files
+  :type: ``list[str]``
+
+  A list of license files to include in the wheel. Supports glob patterns. The default is ``["LICEN[CS]E*", "COPYING*", "NOTICE*", "AUTHORS*"]``. Must not be set if ``project.license-files`` is set.
+
+.. confval:: wheel.cmake
+  :type: ``bool``
+  :default: true
+
+  If set to True (the default), CMake will be run before building the wheel.
+
+.. confval:: wheel.platlib
+  :type: ``bool``
+
+  Target the platlib or the purelib. If not set, the default is to target the platlib if wheel.cmake is true, and the purelib otherwise.
+
+.. confval:: wheel.exclude
+  :type: ``list[str]``
+
+  A set of patterns to exclude from the wheel. This is additive to the SDist exclude patterns. This applies to the final paths in the wheel, and can exclude files from CMake output as well.  Editable installs may not respect this exclusion.
+
+.. confval:: wheel.build-tag
+  :type: ``str``
+
+  The build tag to use for the wheel. If empty, no build tag is used.
+
+.. confval:: backport.find-python
+  :type: ``Version``
+  :default: "3.26.1"
+
+  If CMake is less than this value, backport a copy of FindPython. Set to 0 disable this, or the empty string.
+
+.. confval:: editable.mode
+  :type: ``"redirect" | "inplace"``
+  :default: "redirect"
+
+  Select the editable mode to use. Can be "redirect" (default) or "inplace".
+
+.. confval:: editable.verbose
+  :type: ``bool``
+  :default: true
+
+  Turn on verbose output for the editable mode rebuilds.
+
+.. confval:: editable.rebuild
+  :type: ``bool``
+  :default: false
+
+  Rebuild the project when the package is imported. The build-directory must be set.
+
+.. confval:: build.tool-args
+  :type: ``list[str]``
+
+  Extra args to pass directly to the builder in the build step.
+
+.. confval:: build.targets
+  :type: ``list[str]``
+
+  The build targets to use when building the project. Empty builds the default target.
+
+.. confval:: build.verbose
+  :type: ``bool``
+  :default: false
+
+  Verbose printout when building.
+
+.. confval:: build.requires
+  :type: ``list[str]``
+
+  Additional ``build-system.requires``. Intended to be used in combination with ``overrides``.
+
+.. confval:: install.components
+  :type: ``list[str]``
+
+  The components to install. If empty, all default components are installed.
+
+.. confval:: install.strip
+  :type: ``bool``
+  :default: true
+
+  Whether to strip the binaries. True for release builds on scikit-build-core 0.5+ (0.5-0.10.5 also incorrectly set this for debug builds).
+
+.. confval:: generate[].path
+  :type: ``Path``
+
+  The path (relative to platlib) for the file to generate.
+
+.. confval:: generate[].template
+  :type: ``str``
+
+  The template to use for the file. This includes string.Template style placeholders for all the metadata. If empty, a template-path must be set.
+
+.. confval:: generate[].template-path
+  :type: ``Path``
+
+  The path to the template file. If empty, a template must be set.
+
+.. confval:: generate[].location
+  :type: ``"install" | "build" | "source"``
+  :default: "install"
+
+  The place to put the generated file. The "build" directory is useful for CMake files, and the "install" directory is useful for Python files, usually. You can also write directly to the "source" directory, will overwrite existing files & remember to gitignore the file.
+
+.. confval:: messages.after-failure
+  :type: ``str``
+
+  A message to print after a build failure.
+
+.. confval:: messages.after-success
+  :type: ``str``
+
+  A message to print after a successful build.
+
+.. confval:: search.site-packages
+  :type: ``bool``
+  :default: true
+
+  Add the python build environment site_packages folder to the CMake prefix paths.
+
+.. confval:: metadata
+  :type: ``dict[str,dict[str,Any]]``
+
+  List dynamic metadata fields and hook locations in this table.
+
+.. confval:: strict-config
+  :type: ``bool``
+  :default: true
+
+  Strictly check all config options. If False, warnings will be printed for unknown options. If True, an error will be raised.
+
+.. confval:: experimental
+  :type: ``bool``
+  :default: false
+
+  Enable early previews of features not finalized yet.
+
+.. confval:: minimum-version
+  :type: ``Version``
+  :default: "0.11"  # current version
+
+  If set, this will provide a method for backward compatibility.
+
+.. confval:: build-dir
+  :type: ``str``
+
+  The build directory. Defaults to a temporary directory, but can be set.
+
+.. confval:: fail
+  :type: ``bool``
+  :default: false
+
+  Immediately fail the build. This is only useful in overrides.
diff --git a/noxfile.py b/noxfile.py
@@ -92,6 +92,29 @@ def generate_schema(session: nox.Session) -> None:
     schema_file.write_text(schema_txt)
 
 
+@nox.session(reuse_venv=True, tags=["gen"])
+def generate_config_reference(session: nox.Session) -> None:
+    """
+    (Re)generate configure reference
+    """
+    session.install("-e.")
+    sphinx_txt = session.run(
+        "python",
+        "-m",
+        "scikit_build_core.settings.skbuild_docs",
+        "--format=sphinx",
+        silent=True,
+    )
+    assert isinstance(sphinx_txt, str)
+    configs_file = DIR / "docs/reference/configs.rst"
+    configs_file.write_text(f"""\
+Configurations
+==============
+
+{sphinx_txt}
+""")
+
+
 @nox.session
 def tests(session: nox.Session) -> None:
     """
diff --git a/src/scikit_build_core/settings/documentation.py b/src/scikit_build_core/settings/documentation.py
@@ -5,13 +5,13 @@
 import inspect
 import textwrap
 from pathlib import Path
-from typing import TYPE_CHECKING, TypeVar, cast
+from typing import TYPE_CHECKING, Literal, TypeVar, Union, cast
 
 from packaging.specifiers import SpecifierSet
 from packaging.version import Version
 
 from .. import __version__
-from .._compat.typing import get_args, get_origin
+from .._compat.typing import Annotated, get_args, get_origin
 
 if TYPE_CHECKING:
     from collections.abc import Generator
@@ -56,6 +56,7 @@ def pull_docs(dc: type[object]) -> dict[str, str]:
 @dataclasses.dataclass
 class DCDoc:
     name: str
+    type: str
     default: str
     docs: str
     deprecated: bool = False
@@ -78,6 +79,33 @@ def sanitize_default_field(text: str) -> str:
     return text  # noqa: RET504
 
 
+def is_optional(field: type) -> bool:
+    return get_origin(field) is Union and type(None) in get_args(field)
+
+
+def get_display_type(field_type: type | str) -> str:
+    if isinstance(field_type, str):
+        return field_type
+    if is_optional(field_type):
+        # Special case for optional, we just take the first part
+        return get_display_type(get_args(field_type)[0])
+    # Handle built-ins
+    if get_origin(field_type) is dict:
+        key_display = get_display_type(get_args(field_type)[0])
+        val_display = get_display_type(get_args(field_type)[1])
+        return f"dict[{key_display},{val_display}]"
+    if get_origin(field_type) is list:
+        return f"list[{get_display_type(get_args(field_type)[0])}]"
+    # Handle other typing specials
+    if get_origin(field_type) is Literal:
+        return " | ".join(f'"{x}"' for x in get_args(field_type))
+    if get_origin(field_type) is Annotated:
+        # For annotated assume we always want the second item
+        return get_display_type(get_args(field_type)[1])
+    # Otherwise just get the formatted form of the `type` object
+    return field_type.__name__
+
+
 def mk_docs(dc: type[object], prefix: str = "") -> Generator[DCDoc, None, None]:
     """
     Makes documentation for a dataclass.
@@ -115,6 +143,9 @@ def mk_docs(dc: type[object], prefix: str = "") -> Generator[DCDoc, None, None]:
 
         yield DCDoc(
             name=f"{prefix}{field.name}".replace("_", "-"),
+            type=get_metadata_field(
+                field, "display_type", get_display_type(field.type)
+            ),
             default=sanitize_default_field(default),
             docs=docs[field.name],
             deprecated=get_metadata_field(field, "deprecated", False),  # noqa: FBT003
diff --git a/src/scikit_build_core/settings/skbuild_docs.py b/src/scikit_build_core/settings/skbuild_docs.py
