diff --git a/README.md b/README.md index 30c48fc6..f5821cb4 100644 --- a/README.md +++ b/README.md @@ -140,8 +140,12 @@ More examples are in the All configuration options can be placed in `pyproject.toml`, passed via `-C`/`--config-setting` in build or `-C`/`--config-settings` in `pip` , or set as environment variables. `tool.scikit-build` is used in toml, `skbuild.` for -`-C` options, or `SKBUILD_*` for environment variables. The defaults are listed -below: +`-C` options, or `SKBUILD_*` for environment variables. + +For a full reference and explanation of the variables see the [online +documentation][conf-ref] + +A quick summary and some defaults are listed below: diff --git a/src/scikit_build_core/resources/scikit-build.schema.json b/src/scikit_build_core/resources/scikit-build.schema.json index e95d65c7..5065b415 100644 --- a/src/scikit_build_core/resources/scikit-build.schema.json +++ b/src/scikit_build_core/resources/scikit-build.schema.json @@ -16,14 +16,14 @@ }, "version": { "type": "string", - "description": "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." + "description": "The versions of CMake to allow as a python-compatible specifier." }, "args": { "type": "array", "items": { "type": "string" }, - "description": "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``." + "description": "A list of args to pass to CMake when configuring the project." }, "define": { "type": "object", @@ -88,12 +88,12 @@ "build-type": { "type": "string", "default": "Release", - "description": "The build type to use when building the project. Valid options are: \"Debug\", \"Release\", \"RelWithDebInfo\", \"MinSizeRel\", \"\", etc." + "description": "The build type to use when building the project." }, "source-dir": { "type": "string", "default": ".", - "description": "The source directory to use when building the project. Currently only affects the native builder (not the setuptools plugin)." + "description": "The source directory to use when building the project." }, "targets": { "type": "array", @@ -117,12 +117,12 @@ "version": { "type": "string", "default": ">=1.5", - "description": "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." + "description": "The versions of Ninja to allow." }, "make-fallback": { "type": "boolean", "default": true, - "description": "If Ninja is not present on the system or is older than required, it will be downloaded via PyPI if this is false." + "description": "Use Make as a fallback if a suitable Ninja executable is not found." } } }, @@ -140,7 +140,7 @@ "CRITICAL" ], "default": "WARNING", - "description": "The logging level to display, \"DEBUG\", \"INFO\", \"WARNING\", and \"ERROR\" are possible options." + "description": "The logging level to display." } } }, @@ -165,7 +165,7 @@ "reproducible": { "type": "boolean", "default": true, - "description": "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." + "description": "Try to build a reproducible distribution." }, "cmake": { "type": "boolean", @@ -195,45 +195,45 @@ } } ], - "description": "A list of packages to auto-copy into the wheel. If this is not set, it will default to the first of ``src/``, ``python/``, or ```` 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." + "description": "A list of packages to auto-copy into the wheel." }, "py-api": { "type": "string", "default": "", - "description": "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." + "description": "The Python version tag used in the wheel file." }, "expand-macos-universal-tags": { "type": "boolean", "default": false, - "description": "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." + "description": "Fill out extra tags that are not required." }, "install-dir": { "type": "string", "default": "", - "description": "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\"." + "description": "The CMake install prefix relative to the platlib wheel path." }, "license-files": { "type": "array", "items": { "type": "string" }, - "description": "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." + "description": "A list of license files to include in the wheel. Supports glob patterns." }, "cmake": { "type": "boolean", "default": true, - "description": "If set to True (the default), CMake will be run before building the wheel." + "description": "Run CMake as part of building the wheel." }, "platlib": { "type": "boolean", - "description": "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." + "description": "Target the platlib or the purelib." }, "exclude": { "type": "array", "items": { "type": "string" }, - "description": "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." + "description": "A set of patterns to exclude from the wheel." }, "build-tag": { "type": "string", @@ -249,7 +249,7 @@ "find-python": { "type": "string", "default": "3.26.1", - "description": "If CMake is less than this value, backport a copy of FindPython. Set to 0 disable this, or the empty string." + "description": "If CMake is less than this value, backport a copy of FindPython." } } }, @@ -273,7 +273,7 @@ "rebuild": { "type": "boolean", "default": false, - "description": "Rebuild the project when the package is imported. The build-directory must be set." + "description": "Rebuild the project when the package is imported." } } }, @@ -293,7 +293,7 @@ "items": { "type": "string" }, - "description": "The build targets to use when building the project. Empty builds the default target." + "description": "The build targets to use when building the project." }, "verbose": { "type": "boolean", @@ -305,7 +305,7 @@ "items": { "type": "string" }, - "description": "Additional ``build-system.requires``. Intended to be used in combination with ``overrides``." + "description": "Additional ``build-system.requires``." } } }, @@ -318,11 +318,11 @@ "items": { "type": "string" }, - "description": "The components to install. If empty, all default components are installed." + "description": "The components to install." }, "strip": { "type": "boolean", - "description": "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)." + "description": "Whether to strip the binaries." } } }, @@ -345,7 +345,7 @@ }, "template": { "type": "string", - "description": "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.", + "description": "The template string to use for the file.", "minLength": 1 }, "location": { @@ -355,7 +355,7 @@ "source" ], "default": "install", - "description": "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." + "description": "The place to put the generated file." } } }, @@ -384,7 +384,7 @@ "source" ], "default": "install", - "description": "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." + "description": "The place to put the generated file." } } } @@ -473,7 +473,7 @@ "strict-config": { "type": "boolean", "default": true, - "description": "Strictly check all config options. If False, warnings will be printed for unknown options. If True, an error will be raised." + "description": "Strictly check all config options." }, "experimental": { "type": "boolean", @@ -487,7 +487,7 @@ "build-dir": { "type": "string", "default": "", - "description": "The build directory. Defaults to a temporary directory, but can be set." + "description": "The CMake build directory. Defaults to a unique temporary directory." }, "fail": { "type": "boolean", diff --git a/src/scikit_build_core/settings/documentation.py b/src/scikit_build_core/settings/documentation.py index b3320d4e..1e3f555e 100644 --- a/src/scikit_build_core/settings/documentation.py +++ b/src/scikit_build_core/settings/documentation.py @@ -42,9 +42,7 @@ def pull_docs(dc: type[object]) -> dict[str, str]: assert isinstance(obody, ast.ClassDef) body = obody.body return { - assign.target.id: textwrap.dedent(_get_value(expr.value)) # type: ignore[union-attr] - .strip() - .replace("\n", " ") + assign.target.id: textwrap.dedent(_get_value(expr.value)).strip() # type: ignore[union-attr] for assign, expr in zip(body[:-1], body[1:]) if isinstance(assign, ast.AnnAssign) and isinstance(expr, ast.Expr) } @@ -56,12 +54,9 @@ class DCDoc: type: str default: str docs: str + field: dataclasses.Field[typing.Any] deprecated: bool = False - def __str__(self) -> str: - docs = "\n".join(f"# {s}" for s in textwrap.wrap(self.docs, width=78)) - return f"{docs}\n{self.name} = {self.default}\n" - def sanitize_default_field(text: str) -> str: return text.replace("'", '"').replace("True", "true").replace("False", "false") @@ -137,5 +132,6 @@ def mk_docs(dc: type[object], prefix: str = "") -> Generator[DCDoc, None, None]: type=field.metadata.get("display_type", get_display_type(field.type)), default=sanitize_default_field(default), docs=docs[field.name], + field=field, deprecated=field.metadata.get("deprecated", False), ) diff --git a/src/scikit_build_core/settings/json_schema.py b/src/scikit_build_core/settings/json_schema.py index 4ecf888f..8616dc88 100644 --- a/src/scikit_build_core/settings/json_schema.py +++ b/src/scikit_build_core/settings/json_schema.py @@ -91,10 +91,12 @@ def to_json_schema(dclass: type[Any], *, normalize_keys: bool) -> dict[str, Any] raise ExceptionGroup(msg, errs) docs = pull_docs(dclass) - for k, v in docs.items(): - props[k]["description"] = v - if "DEPRECATED" in v: - props[k]["deprecated"] = True + for field in dataclasses.fields(dclass): + if field.name not in docs: + continue + props[field.name]["description"] = docs[field.name].split("\n", maxsplit=1)[0] + if field.metadata.get("deprecated"): + props[field.name]["deprecated"] = True if normalize_keys: props = {k.replace("_", "-"): v for k, v in props.items()} diff --git a/src/scikit_build_core/settings/skbuild_docs_readme.py b/src/scikit_build_core/settings/skbuild_docs_readme.py index 01723d3b..4bf45c65 100644 --- a/src/scikit_build_core/settings/skbuild_docs_readme.py +++ b/src/scikit_build_core/settings/skbuild_docs_readme.py @@ -1,8 +1,15 @@ from __future__ import annotations +import dataclasses +import textwrap +import typing + from .documentation import mk_docs from .skbuild_model import ScikitBuildSettings +if typing.TYPE_CHECKING: + from .documentation import DCDoc + __all__ = ["mk_skbuild_docs"] @@ -10,13 +17,38 @@ def __dir__() -> list[str]: return __all__ +@dataclasses.dataclass +class Document: + items: list[Item] + + def format(self) -> str: + return "\n".join(item.format() for item in self.items) + + +@dataclasses.dataclass +class Item: + TEMPLATE: typing.ClassVar[str] = textwrap.dedent("""\ + {summary} + {item.name} = {item.default} + """) + item: DCDoc + + def format(self) -> str: + summary = self.item.docs.split("\n", maxsplit=1)[0] + return self.TEMPLATE.format( + item=self.item, + summary=f"# {summary}", + ) + + def mk_skbuild_docs() -> str: """ Makes documentation for the skbuild model. """ - return "\n".join( - str(item) for item in mk_docs(ScikitBuildSettings) if not item.deprecated + doc = Document( + [Item(item) for item in mk_docs(ScikitBuildSettings) if not item.deprecated] ) + return doc.format() if __name__ == "__main__": diff --git a/src/scikit_build_core/settings/skbuild_docs_sphinx.py b/src/scikit_build_core/settings/skbuild_docs_sphinx.py index 2bd52b84..d792a24d 100644 --- a/src/scikit_build_core/settings/skbuild_docs_sphinx.py +++ b/src/scikit_build_core/settings/skbuild_docs_sphinx.py @@ -57,7 +57,7 @@ class Item: .. confval:: {item.name} :type: ``{item.type}``{sphinx_default} - {item.docs} + {docs} ``` """) item: DCDoc @@ -77,9 +77,14 @@ def default(self) -> str: return f"\n :default: {self.item.default}" def format(self) -> str: + # Replace all new-lines with appropriately rst indented lines + docs = self.item.docs.replace("\n", "\n ") + # Replace all lines with pure whitespace to satisfy pre-commit + docs = docs.replace("\n \n", "\n\n") return self.TEMPLATE.format( item=self.item, sphinx_default=self.default(), + docs=docs, ) diff --git a/src/scikit_build_core/settings/skbuild_model.py b/src/scikit_build_core/settings/skbuild_model.py index d25a4a84..a83abd2f 100644 --- a/src/scikit_build_core/settings/skbuild_model.py +++ b/src/scikit_build_core/settings/skbuild_model.py @@ -68,17 +68,32 @@ class CMakeSettings: version: Optional[SpecifierSet] = None """ - 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. + The versions of CMake to allow as a python-compatible specifier. + + If CMake is not present on the system or does not pass this specifier, it will + be downloaded via PyPI if possible with the equivalent specifier used. + + An empty string will disable this check. + + Special cases: + - On scikit-build-core 0.10+ ``CMakeLists.txt`` is the default value otherwise it's + ``>=3.15``. + - If ``CMakeLists.txt`` is passed, the ``cmake_minimum_required`` is read from the + CMakeLists.txt file, using that as the minimum specifier. If the file fails to read, + ``>=3.15`` is used instead. + + .. seealso:: + :confval:`ninja.version` """ args: List[str] = dataclasses.field(default_factory=list) """ - 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``. + A list of args to pass to CMake when configuring the project. + + Setting this in config or envvar will override toml. + + .. seealso:: + :confval:`cmake.define` """ define: Annotated[Dict[str, CMakeSettingsDefine], "EnvVar"] = dataclasses.field( @@ -88,7 +103,9 @@ class CMakeSettings: A table of defines to pass to CMake when configuring the project. Additive. """ - verbose: Optional[bool] = None + verbose: Optional[bool] = dataclasses.field( + default=None, metadata=SettingsFieldMetadata(deprecated=True) + ) """ DEPRECATED in 0.10, use build.verbose instead. """ @@ -96,17 +113,22 @@ class CMakeSettings: build_type: str = "Release" """ The build type to use when building the project. - Valid options are: "Debug", "Release", "RelWithDebInfo", "MinSizeRel", - "", etc. + + Pre-defined CMake options are: ``Debug``, ``Release``, ``RelWithDebInfo``, ``MinSizeRel`` + + Custom values can also be used. """ source_dir: Path = Path() """ - The source directory to use when building the project. Currently only - affects the native builder (not the setuptools plugin). + The source directory to use when building the project. + + Currently only affects the native builder (not the setuptools plugin). """ - targets: Optional[List[str]] = None + targets: Optional[List[str]] = dataclasses.field( + default=None, metadata=SettingsFieldMetadata(deprecated=True) + ) """ DEPRECATED in 0.10; use build.targets instead. """ @@ -131,15 +153,27 @@ class NinjaSettings: version: SpecifierSet = SpecifierSet(">=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. + 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 with the equivalent specifier used. + + An empty string will disable this check. + + .. seealso:: + - :confval:`cmake.version` + - :confval:`ninja.make-fallback` """ make_fallback: bool = True """ - If Ninja is not present on the system or is older than required, - it will be downloaded via PyPI if this is false. + Use Make as a fallback if a suitable Ninja executable is not found. + + If Make is also not available on the system, a ninja dependency is added to the + ``build-system.requires`` according to :confval:`ninja.version`. + + .. seealso:: + :confval:`ninja.version` """ @@ -149,8 +183,7 @@ class LoggingSettings: "WARNING" ) """ - The logging level to display, "DEBUG", "INFO", "WARNING", and "ERROR" are - possible options. + The logging level to display. """ @@ -158,22 +191,29 @@ class LoggingSettings: class SDistSettings: include: List[str] = dataclasses.field(default_factory=list) """ - Files to include in the SDist even if they are skipped by default. - Supports gitignore syntax. + Files to include in the SDist even if they are skipped by default. Supports gitignore syntax. + Always takes precedence over :confval:`sdist.exclude` + + .. seealso:: + :confval:`sdist.exclude` """ exclude: List[str] = dataclasses.field(default_factory=list) """ - Files to exclude from the SDist even if they are included by default. - Supports gitignore syntax. + Files to exclude from the SDist even if they are included by default. Supports gitignore syntax. + + .. seealso:: + :confval:`sdist.include` """ reproducible: bool = 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. + 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. """ cmake: bool = False @@ -191,62 +231,82 @@ class WheelSettings: ), ) """ - A list of packages to auto-copy into the wheel. If this is not set, it will - default to the first of ``src/``, ``python/``, or + A list of packages to auto-copy into the wheel. + + If this is not set, it will default to the first of ``src/``, ``python/``, or ```` 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. + package name inside the wheel. + + If a dict, provides a mapping of package name to source directory. """ py_api: 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 + The Python version tag used in the wheel file. + + 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. + + This value is used to construct ``SKBUILD_SABI_COMPONENT`` CMake variable. """ expand_macos_universal_tags: bool = 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. + 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. """ install_dir: 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". + The CMake install prefix relative to the platlib wheel path. + + You might set this to the package name to install everything under the package namespace + in a pythonic design. + + The original dir is still at ``SKBUILD_PLATLIB_DIR`` (also ``SKBUILD_DATA_DIR``, etc. + are available). + + .. warning:: + EXPERIMENTAL An absolute path will be one level higher than the platlib + root, giving access to "/platlib", "/data", "/headers", and "/scripts". """ license_files: Optional[List[str]] = None """ 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. + + .. warning:: + Must not be set if ``project.license-files`` is set. """ cmake: bool = True """ - If set to True (the default), CMake will be run before building the wheel. + Run CMake as part of building the wheel. """ platlib: Optional[bool] = None """ - 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. + Target the platlib or the purelib. + + If not set, the default is to target the platlib if :confval:`wheel.cmake` is ``true``, + and the purelib otherwise. """ exclude: List[str] = dataclasses.field(default_factory=list) """ - 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. + 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. """ build_tag: str = "" @@ -259,8 +319,9 @@ class WheelSettings: class BackportSettings: find_python: Version = Version("3.26.1") """ - If CMake is less than this value, backport a copy of FindPython. Set to 0 - disable this, or the empty string. + If CMake is less than this value, backport a copy of FindPython. + + Set to ``0`` or an empty string to disable this. """ @@ -278,8 +339,9 @@ class EditableSettings: rebuild: bool = False """ - Rebuild the project when the package is imported. The build-directory must - be set. + Rebuild the project when the package is imported. + + :confval:`build-dir` must be set. """ @@ -292,19 +354,23 @@ class BuildSettings: targets: List[str] = dataclasses.field(default_factory=list) """ - The build targets to use when building the project. Empty builds the - default target. + The build targets to use when building the project. + + If not specified or an empty list, the default target is used. """ verbose: bool = False """ Verbose printout when building. + + Equivalent to ``CMAKE_VERBOSE_MAKEFILE``. """ requires: List[str] = dataclasses.field(default_factory=list) """ - Additional ``build-system.requires``. Intended to be used in combination - with ``overrides``. + Additional ``build-system.requires``. + + Intended to be used in combination with ``overrides``. """ @@ -312,15 +378,23 @@ class BuildSettings: class InstallSettings: components: List[str] = dataclasses.field(default_factory=list) """ - The components to install. If empty, all default components are installed. + The components to install. + + If not specified or an empty list, all default components are installed. """ strip: Optional[bool] = dataclasses.field( default=None, metadata=SettingsFieldMetadata(display_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). + Whether to strip the binaries. + + Equivalent to ``--strip`` in ``cmake install``. + + True for release builds (`Release` or `MinSizeRel`) on scikit-build-core 0.5+. + + .. note:: + 0.5-0.10.5 also incorrectly set this for debug builds. """ @@ -333,21 +407,33 @@ class GenerateSettings: template: 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. + The template string to use for the file. + + Template style placeholders are available for all the metadata. + + Either this or :confval:`generate[].template-path` must be set. + + .. seealso:: + :confval:`generate[].template-path` """ template_path: Optional[Path] = None """ The path to the template file. If empty, a template must be set. + + Either this or :confval:`generate[].template` must be set. + + .. seealso:: + :confval:`generate[].template` """ location: Literal["install", "build", "source"] = "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. + 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. """ @@ -390,8 +476,11 @@ class ScikitBuildSettings: strict_config: bool = True """ - Strictly check all config options. If False, warnings will be - printed for unknown options. If True, an error will be raised. + Strictly check all config options. + + If False, warnings will be printed for unknown options. + + If True, an error will be raised. """ experimental: bool = False @@ -411,7 +500,9 @@ class ScikitBuildSettings: build_dir: str = "" """ - The build directory. Defaults to a temporary directory, but can be set. + The CMake build directory. Defaults to a unique temporary directory. + + This can be set to reuse the build directory from previous runs. """ fail: bool = False diff --git a/tests/test_settings_docs.py b/tests/test_settings_docs.py index 7d144f47..8c8da961 100644 --- a/tests/test_settings_docs.py +++ b/tests/test_settings_docs.py @@ -1,40 +1,58 @@ from __future__ import annotations -from scikit_build_core.settings.documentation import DCDoc, mk_docs -from scikit_build_core.settings.skbuild_docs_readme import mk_skbuild_docs +import textwrap + +from scikit_build_core.settings.documentation import mk_docs +from scikit_build_core.settings.skbuild_docs_readme import ( + mk_skbuild_docs as mk_skbuild_docs_readme, +) +from scikit_build_core.settings.skbuild_docs_sphinx import ( + mk_skbuild_docs as mk_skbuild_docs_sphinx, +) from scikit_build_core.settings.skbuild_model import ScikitBuildSettings -def test_skbuild_docs() -> None: - docs = mk_skbuild_docs() +def test_skbuild_docs_readme() -> None: + docs = mk_skbuild_docs_readme() assert ( "A table of defines to pass to CMake when configuring the project. Additive." in docs ) - assert "DEPRECATED in 0.10, use build.verbose instead." in docs assert "fail = false" in docs + # Deprecated items are not included here + assert "ninja.minimum-version" not in docs -def test_mk_docs() -> None: - docs = set(mk_docs(ScikitBuildSettings)) - +def test_skbuild_docs_sphinx() -> None: + docs = mk_skbuild_docs_sphinx() assert ( - DCDoc( - name="cmake.minimum-version", - type="Version", - default='""', - docs="DEPRECATED in 0.8; use version instead.", - deprecated=True, - ) + textwrap.dedent("""\ + .. confval:: cmake.define + :type: ``EnvVar`` + + A table of defines to pass to CMake when configuring the project. Additive. + """) in docs ) assert ( - DCDoc( - name="install.strip", - type="bool", - default="true", - docs="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).", - deprecated=False, - ) + textwrap.dedent("""\ + .. confval:: ninja.minimum-version + :type: ``Version`` + + DEPRECATED in 0.8; use version instead. + """) in docs ) + + +def test_mk_docs() -> None: + docs = set(mk_docs(ScikitBuildSettings)) + + dcdoc = next(item for item in docs if item.name == "cmake.define") + assert dcdoc.type == "EnvVar" + assert dcdoc.default == "{}" + assert ( + dcdoc.docs + == "A table of defines to pass to CMake when configuring the project. Additive." + ) + assert dcdoc.deprecated is False