docs: Some restructuring

docs/about/projects.md

@@ -0,0 +1,88 @@
+# Projects
+
+There are over 200 projects using scikit-build-core on PyPI. This is a selection
+of some of the projects. Feel free to add your own project to
+`docs/data/projects.toml`. The following selection was primarily constructed by
+looking at the top 8,000 most downloaded projects on PyPI.
+
+<!--[[[cog
+import cog
+import tomllib
+from pathlib import Path
+
+DIR = Path(cog.inFile).parent
+PROJECTS = DIR / "data/projects.toml"
+
+with PROJECTS.open("rb") as f:
+    projects = tomllib.load(f)
+
+for project in projects["project"]:
+    pypi = project["pypi"]
+    github = project["github"]
+    path = project.get("path", "pyproject.toml")
+
+    cog.outl(f"* [{pypi}](https://pypi.org/project/{pypi}) ([source](https://github.com/{github}/blob/HEAD/{path}))")
+]]]-->
+
+- [cmake](https://pypi.org/project/cmake)
+  ([source](https://github.com/scikit-build/cmake-python-distributions/blob/HEAD/pyproject.toml))
+- [ninja](https://pypi.org/project/ninja)
+  ([source](https://github.com/scikit-build/ninja-python-distributions/blob/HEAD/pyproject.toml))
+- [pyzmq](https://pypi.org/project/pyzmq)
+  ([source](https://github.com/zeromq/pyzmq/blob/HEAD/pyproject.toml))
+- [lightgbm](https://pypi.org/project/lightgbm)
+  ([source](https://github.com/microsoft/LightGBM/blob/HEAD/python-package/pyproject.toml))
+- [phik](https://pypi.org/project/phik)
+  ([source](https://github.com/kaveio/phik/blob/HEAD/pyproject.toml))
+- [clang-format](https://pypi.org/project/clang-format)
+  ([source](https://github.com/ssciwr/clang-format-wheel/blob/HEAD/pyproject.toml))
+- [llama-cpp-python](https://pypi.org/project/llama-cpp-python)
+  ([source](https://github.com/abetlen/llama-cpp-python/blob/HEAD/pyproject.toml))
+- [coreforecast](https://pypi.org/project/coreforecast)
+  ([source](https://github.com/Nixtla/coreforecast/blob/HEAD/pyproject.toml))
+- [sparse-dot-topn](https://pypi.org/project/sparse-dot-topn)
+  ([source](https://github.com/ing-bank/sparse_dot_topn/blob/HEAD/pyproject.toml))
+- [spglib](https://pypi.org/project/spglib)
+  ([source](https://github.com/spglib/spglib/blob/HEAD/pyproject.toml))
+- [awkward-cpp](https://pypi.org/project/awkward-cpp)
+  ([source](https://github.com/scikit-hep/awkward/blob/HEAD/awkward-cpp/pyproject.toml))
+- [OpenEXR](https://pypi.org/project/OpenEXR)
+  ([source](https://github.com/AcademySoftwareFoundation/OpenEXR/blob/HEAD/pyproject.toml))
+- [iminuit](https://pypi.org/project/iminuit)
+  ([source](https://github.com/scikit-hep/iminuit/blob/HEAD/pyproject.toml))
+- [boost-histogram](https://pypi.org/project/boost-histogram)
+  ([source](https://github.com/scikit-hep/iminuit/blob/HEAD/pyproject.toml))
+- [astyle](https://pypi.org/project/astyle)
+  ([source](https://github.com/Freed-Wu/astyle-wheel/blob/HEAD/pyproject.toml))
+- [lammps](https://pypi.org/project/lammps)
+  ([source](https://github.com/njzjz/lammps-wheel/blob/HEAD/pyproject.toml))
+- [llamacpp](https://pypi.org/project/llamacpp)
+  ([source](https://github.com/thomasantony/llamacpp-python/blob/HEAD/pyproject.toml))
+- [nodejs-wheel](https://pypi.org/project/nodejs-wheel)
+  ([source](https://github.com/njzjz/nodejs-wheel/blob/HEAD/pyproject.toml))
+- [pygram11](https://pypi.org/project/pygram11)
+([source](https://github.com/douglasdavis/pygram11/blob/HEAD/pyproject.toml))
+<!--[[[end]]] (checksum: 8067a47175c7598c556172d67c1d1adc) -->
+
+In addition, most of the [RAPIDSAI](https://github.com/rapidsai) projects use
+scikit-build-core, but they are not published on PyPI. A few of them are:
+
+- CuDF
+  ([source](https://github.com/rapidsai/cudf/blob/HEAD/python/cudf/pyproject.toml))
+- CuGraph
+  ([source](https://github.com/rapidsai/cugraph/blob/HEAD/python/cugraph/pyproject.toml))
+- CuML
+  ([source](https://github.com/rapidsai/cuml/blob/HEAD/python/cuml/pyproject.toml))
+- CuSpatial
+  ([source](https://github.com/rapidsai/cuspatial/blob/HEAD/python/cuspatial/pyproject.toml))
+- RMM
+  ([source](https://github.com/rapidsai/rmm/blob/HEAD/python/rmm/pyproject.toml))
+- Raft
+  ([source](https://github.com/rapidsai/raft/blob/HEAD/python/pylibraft/pyproject.toml))
+
+The [Insight Toolkit (ITK)](https://docs.itk.org), the initial target project
+for scikit-build classic, has
+[transitioned to sckit-build-core](https://github.com/InsightSoftwareConsortium/ITKPythonPackage/blob/master/scripts/pyproject.toml.in).
+ITK currently provides one example of a production SWIG-based deployment. In
+addition, dozens of
+[ITK-based extension packages are configured with scikit-build-core](https://github.com/topics/itk-module).

docs/configuration/dynamic.md

@@ -0,0 +1,137 @@
+# Dynamic metadata
+
+Scikit-build-core supports dynamic metadata with three built-in plugins.
+
+:::{warning}
+
+Your package and third-party packages can also extend these with new plugins,
+but this is currently not ready for development outside of scikit-build-core;
+`tool.scikit-build.experimental=true` is required to use plugins that are not
+shipped with scikit-build-core, since the interface is provisional and may
+change between _minor_ versions.
+
+:::
+
+## `version`: Setuptools-scm
+
+You can use [setuptools-scm](https://github.com/pypa/setuptools-scm) to pull the
+version from VCS:
+
+```toml
+[project]
+name = "mypackage"
+dynamic = ["version"]
+
+[tool.scikit-build]
+metadata.version.provider = "scikit_build_core.metadata.setuptools_scm"
+sdist.include = ["src/package/_version.py"]
+
+[tool.setuptools_scm]  # Section required
+write_to = "src/package/_version.py"
+```
+
+This sets the python project version according to
+[git tags](https://github.com/pypa/setuptools-scm/blob/fb261332d9b46aa5a258042d85baa5aa7b9f4fa2/README.rst#default-versioning-scheme)
+or a
+[`.git_archival.txt`](https://github.com/pypa/setuptools-scm/blob/fb261332d9b46aa5a258042d85baa5aa7b9f4fa2/README.rst#git-archives)
+file, or equivalents for other VCS systems.
+
+If you need to set the CMake project version without scikit-build-core (which
+provides `${SKBUILD_PROJECT_VERSION}`), you can use something like
+[`DynamicVersion` module](https://github.com/LecrisUT/CMakeExtraUtils/blob/180604da50a3c3588f9d04e4ebc6abb4e5a0d234/cmake/DynamicVersion.md)
+from
+[github.com/LecrisUT/CMakeExtraUtils](https://github.com/LecrisUT/CMakeExtraUtils):
+
+```cmake
+# Import `CMakeExtraUtils` or bundle `DynamicVersion.cmake` from there
+include(DynamicVersion)
+
+# Set ${PROJECT_VERSION} according to git tag or `.git_archival.txt`
+dynamic_version()
+
+project(MyPackage VERSION ${PROJECT_VERSION})
+```
+
+## `version`: Regex
+
+If you want to pull a string-valued expression (usually version) from an
+existing file, you can the integrated `regex` plugin to pull the information.
+
+```toml
+name = "mypackage"
+dynamic = ["version"]
+
+[tool.scikit-build.metadata.version]
+provider = "scikit_build_core.metadata.regex"
+input = "src/mypackage/__init__.py"
+```
+
+You can set a custom regex with `regex=`. By default when targeting version, you
+get a reasonable regex for python files,
+`'(?i)^(__version__|VERSION)(?: ?\: ?str)? *= *([\'"])v?(?P<value>.+?)\2'`. You
+can set `result` to a format string to process the matches; the default is
+`"{value}"`. You can also specify a regex for `remove=` which will strip any
+matches from the final result. A more complex example:
+
+```toml
+[tool.scikit-build.metadata.version]
+provider = "scikit_build_core.metadata.regex"
+input = "src/mypackage/version.hpp"
+regex = '''(?sx)
+\#define \s+ VERSION_MAJOR \s+ (?P<major>\d+) .*?
+\#define \s+ VERSION_MINOR \s+ (?P<minor>\d+) .*?
+\#define \s+ VERSION_PATCH \s+ (?P<patch>\d+) .*?
+\#define \s+ VERSION_DEV   \s+ (?P<dev>\d+)   .*?
+'''
+result = "{major}.{minor}.{patch}dev{dev}"
+remove = "dev0"
+```
+
+This will remove the "dev" tag when it is equal to 0.
+
+```{versionchanged} 0.10
+
+Support for `result` and `remove` added.
+
+```
+
+## `readme`: Fancy-pypi-readme
+
+You can use
+[hatch-fancy-pypi-readme](https://github.com/hynek/hatch-fancy-pypi-readme) to
+render your README:
+
+```toml
+[project]
+name = "mypackage"
+dynamic = ["readme"]
+
+[tool.scikit-build]
+metadata.readme.provider = "scikit_build_core.metadata.fancy_pypi_readme"
+
+# tool.hatch.metadata.hooks.fancy-pypi-readme options here
+```
+
+## Generate files with dynamic metadata
+
+You can write out metadata to file(s) as well. Other info might become available
+here in the future, but currently it supports anything available as strings in
+metadata. (Note that arrays like this are only supported in TOML configuration.)
+
+```toml
+[[tool.scikit-build.generate]]
+path = "package/_version.py"
+template = '''
+version = "${version}"
+'''
+```
+
+`template` or `template-path` is required; this uses {class}`string.Template`
+formatting. There are three options for output location; `location = "install"`
+(the default) will go to the wheel, `location = "build"` will go to the CMake
+build directory, and `location = "source"` will write out to the source
+directory (be sure to .gitignore this file. It will automatically be added to
+your SDist includes. It will overwrite existing files).
+
+The path is generally relative to the base of the wheel / build dir / source
+dir, depending on which location you pick.

docs/configuration.md → docs/configuration/index.md

@@ -539,150 +539,6 @@ You can pass raw arguments directly to the build tool, as well:
 
 ```
 
-## Dynamic metadata
-
-Scikit-build-core supports dynamic metadata with three built-in plugins.
-
-:::{tab} Setuptools-scm
-
-You can use [setuptools-scm](https://github.com/pypa/setuptools-scm) to pull the
-version from VCS:
-
-```toml
-[project]
-name = "mypackage"
-dynamic = ["version"]
-
-[tool.scikit-build]
-metadata.version.provider = "scikit_build_core.metadata.setuptools_scm"
-sdist.include = ["src/package/_version.py"]
-
-[tool.setuptools_scm]  # Section required
-write_to = "src/package/_version.py"
-```
-
-This sets the python project version according to
-[git tags](https://github.com/pypa/setuptools-scm/blob/fb261332d9b46aa5a258042d85baa5aa7b9f4fa2/README.rst#default-versioning-scheme)
-or a
-[`.git_archival.txt`](https://github.com/pypa/setuptools-scm/blob/fb261332d9b46aa5a258042d85baa5aa7b9f4fa2/README.rst#git-archives)
-file, or equivalents for other VCS systems.
-
-If you need to set the CMake project version without scikit-build-core (which
-provides `${SKBUILD_PROJECT_VERSION}`), you can use something like
-[`DynamicVersion` module](https://github.com/LecrisUT/CMakeExtraUtils/blob/180604da50a3c3588f9d04e4ebc6abb4e5a0d234/cmake/DynamicVersion.md)
-from
-[github.com/LecrisUT/CMakeExtraUtils](https://github.com/LecrisUT/CMakeExtraUtils):
-
-```cmake
-# Import `CMakeExtraUtils` or bundle `DynamicVersion.cmake` from there
-include(DynamicVersion)
-
-# Set ${PROJECT_VERSION} according to git tag or `.git_archival.txt`
-dynamic_version()
-
-project(MyPackage VERSION ${PROJECT_VERSION})
-```
-
-:::
-
-:::{tab} Fancy-pypi-readme
-
-You can use
-[hatch-fancy-pypi-readme](https://github.com/hynek/hatch-fancy-pypi-readme) to
-render your README:
-
-```toml
-[project]
-name = "mypackage"
-dynamic = ["readme"]
-
-[tool.scikit-build]
-metadata.readme.provider = "scikit_build_core.metadata.fancy_pypi_readme"
-
-# tool.hatch.metadata.hooks.fancy-pypi-readme options here
-```
-
-:::
-
-:::{tab} Regex
-
-If you want to pull a string-valued expression (usually version) from an
-existing file, you can the integrated `regex` plugin to pull the information.
-
-```toml
-name = "mypackage"
-dynamic = ["version"]
-
-[tool.scikit-build.metadata.version]
-provider = "scikit_build_core.metadata.regex"
-input = "src/mypackage/__init__.py"
-```
-
-You can set a custom regex with `regex=`. By default when targeting version, you
-get a reasonable regex for python files,
-`'(?i)^(__version__|VERSION)(?: ?\: ?str)? *= *([\'"])v?(?P<value>.+?)\2'`. You
-can set `result` to a format string to process the matches; the default is
-`"{value}"`. You can also specify a regex for `remove=` which will strip any
-matches from the final result. A more complex example:
-
-```toml
-[tool.scikit-build.metadata.version]
-provider = "scikit_build_core.metadata.regex"
-input = "src/mypackage/version.hpp"
-regex = '''(?sx)
-\#define \s+ VERSION_MAJOR \s+ (?P<major>\d+) .*?
-\#define \s+ VERSION_MINOR \s+ (?P<minor>\d+) .*?
-\#define \s+ VERSION_PATCH \s+ (?P<patch>\d+) .*?
-\#define \s+ VERSION_DEV   \s+ (?P<dev>\d+)   .*?
-'''
-result = "{major}.{minor}.{patch}dev{dev}"
-remove = "dev0"
-```
-
-This will remove the "dev" tag when it is equal to 0.
-
-::::{versionchanged} 0.10
-
-Support for `result` and `remove` added.
-
-::::
-
-:::
-
-:::{warning}
-
-Your package and third-party packages can also extend these with new plugins,
-but this is currently not ready for development outside of scikit-build-core;
-`tool.scikit-build.experimental=true` is required to use plugins that are not
-shipped with scikit-build-core, since the interface is provisional and may
-change between _minor_ versions.
-
-:::
-
-### Writing metadata
-
-You can write out metadata to file(s) as well. Other info might become available
-here in the future, but currently it supports anything available as strings in
-metadata. (Note that arrays like this are only supported in TOML configuration.)
-
-```toml
-[[tool.scikit-build.generate]]
-path = "package/_version.py"
-template = '''
-version = "${version}"
-'''
-```
-
-`template` or `template-path` is required; this uses {class}`string.Template`
-formatting. There are three options for output location; `location = "install"`
-(the default) will go to the wheel, `location = "build"` will go to the CMake
-build directory, and `location = "source"` will write out to the source
-directory (be sure to .gitignore this file. It will automatically be added to
-your SDist includes. It will overwrite existing files).
-
-The path is generally relative to the base of the wheel / build dir / source
-dir, depending on which location you pick.
-
 ## Editable installs
 
 Experimental support for editable installs is provided, with some caveats and