Skip to content

Commit

Permalink
docs: more generation of docs
Browse files Browse the repository at this point in the history 
Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>
  • Loading branch information
@henryiii
henryiii committed Aug 8, 2023
1 parent 52ad4df commit e3a8104
Show file tree
Hide file tree
Showing 6 changed files with 247 additions and 114 deletions.
144 changes: 87 additions & 57 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -115,106 +115,136 @@ as environment variables. `tool.scikit-build` is used in toml, `skbuild.` for
`-C` options, or `SKBUILD_*` for environment variables. The defaults are listed
below:

<!-- [[[cog
from scikit_build_core.settings.skbuild_docs import mk_skbuild_docs
print("\n```toml\n[tool.scikit-build]")
print(mk_skbuild_docs())
print("```\n")
]]] -->

```toml
[tool.scikit-build]
# The PEP 517 build hooks will add ninja and/or cmake if the versions on the
# system are not at least these versions. Disabled by an empty string.
# The minimum version of CMake to use. If CMake is not present on the system or
# is older than this, it will be downloaded via PyPI if possible. An empty
# string will disable this check.
cmake.minimum-version = "3.15"
ninja.minimum-version = "1.5"

# Fallback on gmake/make if available and ninja is missing (Unix). Will only
# fallback on platforms without a known ninja wheel.
ninja.make-fallback = true

# Extra args for CMake. Pip, unlike build, does not support lists, so semicolon
# can be used to separate. Setting this in config or envvar will override the
# entire list. 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. See also ``cmake.define``.
cmake.args = []

# This activates verbose builds
# A table of defines to pass to CMake when configuring the project. Additive.
cmake.define = {}

# Verbose printout when building.
cmake.verbose = false

# This controls the CMake build type
# The build type to use when building the project. Valid options are: "Debug",
# "Release", "RelWithDebInfo", "MinSizeRel", "", etc.
cmake.build-type = "Release"

# The targets to build - empty builds all default targets.
# The source directory to use when building the project. Currently only affects
# the native builder (not the setuptools plugin).
cmake.source-dir = ""

# The build targets to use when building the project. Empty builds the default
# target.
cmake.targets = []

# Display logs at or above this level.
# The minimum version of Ninja to use. If Ninja is not present on the system or
# is older than this, it will be downloaded via PyPI if possible. An empty
# string will disable this check.
ninja.minimum-version = "1.5"

# If CMake is not present on the system or is older required, it will be
# downloaded via PyPI if possible. An empty string will disable this check.
ninja.make-fallback = true

# The logging level to display, "DEBUG", "INFO", "WARNING", and "ERROR" are
# possible options.
logging.level = "WARNING"

# Include and exclude patterns, in gitignore syntax. Include overrides exclude.
# Wheels include packages included in the sdist; CMake has the final say.
# Files to include in the SDist even if they are skipped by default. Supports
# gitignore syntax.
sdist.include = []

# Files to exclude from the SDist even if they are included by default. Supports
# gitignore syntax.
sdist.exclude = []

# Make reproducible SDists (Python 3.9+ and UNIX recommended). Respects
# SOURCE_DATE_EPOCH when true (the default).
# 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.
sdist.reproducible = true

# The root-level packages to include. Special default: if not given, the package
# is auto-discovered if it's name matches the main name.
# A list of packages to auto-copy into the wheel. If this is not set, it will
# default to the first of ``src/<package>`` or ``<package>`` if they exist. The
# prefix(s) will be stripped from the package name inside the wheel.
wheel.packages = ["src/<package>", "<package>"]

# Setting py-api to "cp37" would build ABI3 wheels for Python 3.7+. If CPython
# is less than this value, or on PyPy, this will be ignored. Setting the api to
# "py3" or "py2.py3" would build wheels that don't depend on Python (ctypes,
# etc).
# The Python tags. The default (empty string) will use the default Python
# version. You can also set this to "cp37" to enable the CPython 3.7+ 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.
wheel.py-api = ""

# Setting this to true will expand tags (universal2 will add Intel and Apple
# Silicon tags, for pip <21.0.1 compatibility).
# 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.
wheel.expand-macos-universal-tags = false

# This allows you to change the install dir, such as to the package name. The
# original dir is still at SKBUILD_PLATLIB_DIR (also SKBUILD_DATA_DIR, etc. are
# available)
wheel.install-dir = "."
# 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".
wheel.install-dir = ""

# The licence file(s) to include in the wheel metadata directory.
# A list of license files to include in the wheel. Supports glob patterns.
wheel.license-files = ["LICEN[CS]E*", "COPYING*", "NOTICE*", "AUTHORS*"]

# Strip the binaries. Defaults to True for scikit-build-core 0.5+.
install.strip = true

# Components to install. Leave empty to install all components.
install.components = []

# This will backport an internal copy of FindPython if CMake is less than this
# value. Set to 0 or the empty string to disable. The default will be kept in
# sync with the version of FindPython stored in scikit-build-core.
# If CMake is less than this value, backport a copy of FindPython. Set to 0
# disable this, or the empty string.
backport.find-python = "3.26.1"

# This is the only editable mode currently
# Select the editable mode to use. Currently only "redirect" is supported.
editable.mode = "redirect"

# Enable auto rebuilds on import (experimental)
# Turn on verbose output for the editable mode rebuilds.
editable.verbose = true

# Rebuild the project when the package is imported. The build-directory must be
# set.
editable.rebuild = false

# Display output on stderr while rebuilding on import
editable.verbose = true
# The components to install. If empty, all default components are installed.
install.components = []

# Enable experimental features if any are available
experimental = false
# Whether to strip the binaries. True for scikit-build-core 0.5+.
install.strip = false

# List dynamic metadata fields and hook locations in this table.
metadata = {}

# Strictly validate config options
# Strictly check all config options. If False, warnings will be printed for
# unknown options. If True, an error will be raised.
strict-config = true

# This provides some backward compatibility if set. Defaults to the latest
# scikit-build-core version.
minimum-version = "0.2" # current version
# Enable early previews of features not finalized yet.
experimental = false

# If set, this will provide a method for backward compatibility.
minimum-version = "0.4" # current version

# Build directory (empty will use a temporary directory). {cache_tag} and
# {wheel_tag} are available to provide a unique directory per interpreter.
# The build directory. Defaults to a temporary directory, but can be set.
build-dir = ""

[tool.scikit-build.cmake.define]
# Put CMake defines in this table.

[tool.scikit-build.metadata]
# List dynamic metadata fields and hook locations in this table
```

<!-- [[[end]]] -->

Most CMake environment variables should be supported, and `CMAKE_ARGS` can be
used to set extra CMake args. `ARCHFLAGS` is used to specify macOS universal2 or
cross-compiles, just like setuptools.
Expand Down
12 changes: 12 additions & 0 deletions noxfile.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,18 @@ def tests(session: nox.Session) -> None:
_run_tests(session, extras=["test-meta,test-numpy,test-schema"])


@nox.session(reuse_venv=True)
def readme(session: nox.Session) -> None:
"""
Update the readme with cog. Pass --check to check instead.
"""

args = session.posargs or ["-r"]

session.install("-e.", "cogapp")
session.run("cog", "-P", *args, "README.md")


@nox.session
def minimums(session: nox.Session) -> None:
"""
Expand Down
46 changes: 26 additions & 20 deletions src/scikit_build_core/resources/scikit-build.schema.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,14 @@
"minimum-version": {
"type": "string",
"default": "3.15",
"description": "The minimum version of CMake to use. If CMake is older than this, it will be upgraded via PyPI if possible. An empty string will disable this check."
"description": "The minimum version of CMake to use. If CMake is not present on the system or is older than this, it will be downloaded via PyPI if possible. An empty string will disable this check."
},
"args": {
"type": "array",
"items": {
"type": "string"
},
"description": "A list of args to pass to CMake when configuring the project."
"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``."
},
"define": {
"type": "object",
Expand All @@ -33,7 +33,7 @@
"verbose": {
"type": "boolean",
"default": false,
"description": "Verbose printout when building"
"description": "Verbose printout when building."
},
"build-type": {
"type": "string",
Expand Down Expand Up @@ -61,12 +61,12 @@
"minimum-version": {
"type": "string",
"default": "1.5",
"description": "The minimum version of Ninja to use. If Ninja is older than this, it will be upgraded via PyPI if possible. An empty string will disable this check."
"description": "The minimum version of Ninja to use. If Ninja is not present on the system or is older than this, it will be downloaded via PyPI if possible. An empty string will disable this check."
},
"make-fallback": {
"type": "boolean",
"default": true,
"description": "If make is present, do not add ninja if missing."
"description": "If CMake is not present on the system or is older required, it will be downloaded via PyPI if possible. An empty string will disable this check."
}
}
},
Expand All @@ -77,7 +77,7 @@
"level": {
"type": "string",
"default": "WARNING",
"description": "The logging level to display."
"description": "The logging level to display, \"DEBUG\", \"INFO\", \"WARNING\", and \"ERROR\" are possible options."
}
}
},
Expand All @@ -90,19 +90,24 @@
"items": {
"type": "string"
},
"description": "Files to include in the SDist even if they are skipped by default."
"description": "Files to include in the SDist even if they are skipped by default. Supports gitignore syntax."
},
"exclude": {
"type": "array",
"items": {
"type": "string"
},
"description": "Files to exclude from the SDist even if they are included by default."
"description": "Files to exclude from the SDist even if they are included by default. Supports gitignore syntax."
},
"reproducible": {
"type": "boolean",
"default": true,
"description": "If set to True, try to build a reproducible distribution. ``SOURCE_DATE_EPOCH`` will be used for timestamps, or a fixed value if not set."
"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."
},
"cmake": {
"type": "boolean",
"default": false,
"description": "If set to True, CMake will be run before building the SDist."
}
}
},
Expand All @@ -115,12 +120,12 @@
"items": {
"type": "string"
},
"description": "A list of packages to auto-copy into the wheel. If this is None, it will default to the first of ``src/<package>`` or ``<package>`` if they exist. The prefix(s) will be stripped from the package name inside the wheel."
"description": "A list of packages to auto-copy into the wheel. If this is not set, it will default to the first of ``src/<package>`` or ``<package>`` if they exist. The prefix(s) will be stripped from the package name inside 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 \"cp37\" to enable the CPython 3.7+ 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. For the stable ABI, the CMake variable SKBUILD_SOABI will be set to abi3 on Unix-like systems (empty on Windows). FindPython doesn't have a way to target python3.dll instead of python3N.dll, so this is harder to use on Windows. The ABI tag is inferred from this tag."
"description": "The Python tags. The default (empty string) will use the default Python version. You can also set this to \"cp37\" to enable the CPython 3.7+ 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."
},
"expand-macos-universal-tags": {
"type": "boolean",
Expand Down Expand Up @@ -152,14 +157,6 @@
}
}
},
"metadata": {
"type": "object",
"patternProperties": {
".+": {
"type": "object"
}
}
},
"editable": {
"type": "object",
"additionalProperties": false,
Expand Down Expand Up @@ -190,14 +187,23 @@
"items": {
"type": "string"
},
"description": "The components to install. If empty, the default is used."
"description": "The components to install. If empty, all default components are installed."
},
"strip": {
"type": "boolean",
"description": "Whether to strip the binaries. True for scikit-build-core 0.5+."
}
}
},
"metadata": {
"type": "object",
"patternProperties": {
".+": {
"type": "object"
}
},
"description": "List dynamic metadata fields and hook locations in this table."
},
"strict-config": {
"type": "boolean",
"default": true,
Expand Down
39 changes: 39 additions & 0 deletions src/scikit_build_core/settings/documentation.py
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,11 @@
from __future__ import annotations

import ast
import dataclasses
import inspect
import sys
import textwrap
from collections.abc import Generator

__all__ = ["pull_docs"]

Expand Down Expand Up @@ -34,3 +36,40 @@ def pull_docs(dc: type[object]) -> dict[str, str]:
for assign, expr in zip(body[:-1], body[1:])
if isinstance(assign, ast.AnnAssign) and isinstance(expr, ast.Expr)
}


@dataclasses.dataclass
class DCDoc:
name: str
default: str
docs: str

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 mk_docs(dc: type[object], prefix: str = "") -> Generator[DCDoc, None, None]:
"""
Makes documentation for a dataclass.
"""
assert dataclasses.is_dataclass(dc)
docs = pull_docs(dc)

for field in dataclasses.fields(dc):
if dataclasses.is_dataclass(field.type):
yield from mk_docs(field.type, prefix=f"{prefix}{field.name}.")
continue

if field.default is not dataclasses.MISSING:
default = repr(field.default)
elif field.default_factory is not dataclasses.MISSING:
default = repr(field.default_factory())
else:
default = ""

yield DCDoc(
f"{prefix}{field.name}".replace("_", "-"),
default.replace("'", '"').replace("True", "true").replace("False", "false"),
docs[field.name],
)
Loading

0 comments on commit e3a8104

Please sign in to comment.