Skip to content

Commit 42f82b4

Browse files
LecrisUTLecrisUT
authored
docs: some restructuring (#997)
I have caught an issue with the colon fencing breaking the set, while tick fencing works fine. But the section still feels off because the tabs are too big and specialized, e.g. it is not clear where `warning` applies or `Writing metadata` subsection. I think it would flow more clearly if we move it away to a separate document.
1 parent a3c007d commit 42f82b4

File tree

14 files changed

+279
-244
lines changed

14 files changed

+279
-244
lines changed

‎docs/changelog.md‎ renamed to ‎docs/about/changelog.md‎

File renamed without changes.

‎docs/about/projects.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Projects
2+
3+
There are over 200 projects using scikit-build-core on PyPI. This is a selection
4+
of some of the projects. Feel free to add your own project to
5+
`docs/data/projects.toml`. The following selection was primarily constructed by
6+
looking at the top 8,000 most downloaded projects on PyPI.
7+
8+
<!--[[[cog
9+
import cog
10+
import tomllib
11+
from pathlib import Path
12+
13+
DIR = Path(cog.inFile).parent
14+
PROJECTS = DIR / "data/projects.toml"
15+
16+
with PROJECTS.open("rb") as f:
17+
projects = tomllib.load(f)
18+
19+
for project in projects["project"]:
20+
pypi = project["pypi"]
21+
github = project["github"]
22+
path = project.get("path", "pyproject.toml")
23+
24+
cog.outl(f"* [{pypi}](https://pypi.org/project/{pypi}) ([source](https://github.com/{github}/blob/HEAD/{path}))")
25+
]]]-->
26+
27+
- [cmake](https://pypi.org/project/cmake)
28+
([source](https://github.com/scikit-build/cmake-python-distributions/blob/HEAD/pyproject.toml))
29+
- [ninja](https://pypi.org/project/ninja)
30+
([source](https://github.com/scikit-build/ninja-python-distributions/blob/HEAD/pyproject.toml))
31+
- [pyzmq](https://pypi.org/project/pyzmq)
32+
([source](https://github.com/zeromq/pyzmq/blob/HEAD/pyproject.toml))
33+
- [lightgbm](https://pypi.org/project/lightgbm)
34+
([source](https://github.com/microsoft/LightGBM/blob/HEAD/python-package/pyproject.toml))
35+
- [phik](https://pypi.org/project/phik)
36+
([source](https://github.com/kaveio/phik/blob/HEAD/pyproject.toml))
37+
- [clang-format](https://pypi.org/project/clang-format)
38+
([source](https://github.com/ssciwr/clang-format-wheel/blob/HEAD/pyproject.toml))
39+
- [llama-cpp-python](https://pypi.org/project/llama-cpp-python)
40+
([source](https://github.com/abetlen/llama-cpp-python/blob/HEAD/pyproject.toml))
41+
- [coreforecast](https://pypi.org/project/coreforecast)
42+
([source](https://github.com/Nixtla/coreforecast/blob/HEAD/pyproject.toml))
43+
- [sparse-dot-topn](https://pypi.org/project/sparse-dot-topn)
44+
([source](https://github.com/ing-bank/sparse_dot_topn/blob/HEAD/pyproject.toml))
45+
- [spglib](https://pypi.org/project/spglib)
46+
([source](https://github.com/spglib/spglib/blob/HEAD/pyproject.toml))
47+
- [awkward-cpp](https://pypi.org/project/awkward-cpp)
48+
([source](https://github.com/scikit-hep/awkward/blob/HEAD/awkward-cpp/pyproject.toml))
49+
- [OpenEXR](https://pypi.org/project/OpenEXR)
50+
([source](https://github.com/AcademySoftwareFoundation/OpenEXR/blob/HEAD/pyproject.toml))
51+
- [iminuit](https://pypi.org/project/iminuit)
52+
([source](https://github.com/scikit-hep/iminuit/blob/HEAD/pyproject.toml))
53+
- [boost-histogram](https://pypi.org/project/boost-histogram)
54+
([source](https://github.com/scikit-hep/iminuit/blob/HEAD/pyproject.toml))
55+
- [astyle](https://pypi.org/project/astyle)
56+
([source](https://github.com/Freed-Wu/astyle-wheel/blob/HEAD/pyproject.toml))
57+
- [lammps](https://pypi.org/project/lammps)
58+
([source](https://github.com/njzjz/lammps-wheel/blob/HEAD/pyproject.toml))
59+
- [llamacpp](https://pypi.org/project/llamacpp)
60+
([source](https://github.com/thomasantony/llamacpp-python/blob/HEAD/pyproject.toml))
61+
- [nodejs-wheel](https://pypi.org/project/nodejs-wheel)
62+
([source](https://github.com/njzjz/nodejs-wheel/blob/HEAD/pyproject.toml))
63+
- [pygram11](https://pypi.org/project/pygram11)
64+
([source](https://github.com/douglasdavis/pygram11/blob/HEAD/pyproject.toml))
65+
<!--[[[end]]] (checksum: 8067a47175c7598c556172d67c1d1adc) -->
66+
67+
In addition, most of the [RAPIDSAI](https://github.com/rapidsai) projects use
68+
scikit-build-core, but they are not published on PyPI. A few of them are:
69+
70+
- CuDF
71+
([source](https://github.com/rapidsai/cudf/blob/HEAD/python/cudf/pyproject.toml))
72+
- CuGraph
73+
([source](https://github.com/rapidsai/cugraph/blob/HEAD/python/cugraph/pyproject.toml))
74+
- CuML
75+
([source](https://github.com/rapidsai/cuml/blob/HEAD/python/cuml/pyproject.toml))
76+
- CuSpatial
77+
([source](https://github.com/rapidsai/cuspatial/blob/HEAD/python/cuspatial/pyproject.toml))
78+
- RMM
79+
([source](https://github.com/rapidsai/rmm/blob/HEAD/python/rmm/pyproject.toml))
80+
- Raft
81+
([source](https://github.com/rapidsai/raft/blob/HEAD/python/pylibraft/pyproject.toml))
82+
83+
The [Insight Toolkit (ITK)](https://docs.itk.org), the initial target project
84+
for scikit-build classic, has
85+
[transitioned to sckit-build-core](https://github.com/InsightSoftwareConsortium/ITKPythonPackage/blob/master/scripts/pyproject.toml.in).
86+
ITK currently provides one example of a production SWIG-based deployment. In
87+
addition, dozens of
88+
[ITK-based extension packages are configured with scikit-build-core](https://github.com/topics/itk-module).

‎docs/configuration/dynamic.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# Dynamic metadata
2+
3+
Scikit-build-core supports dynamic metadata with three built-in plugins.
4+
5+
:::{warning}
6+
7+
Your package and third-party packages can also extend these with new plugins,
8+
but this is currently not ready for development outside of scikit-build-core;
9+
`tool.scikit-build.experimental=true` is required to use plugins that are not
10+
shipped with scikit-build-core, since the interface is provisional and may
11+
change between _minor_ versions.
12+
13+
:::
14+
15+
## `version`: Setuptools-scm
16+
17+
You can use [setuptools-scm](https://github.com/pypa/setuptools-scm) to pull the
18+
version from VCS:
19+
20+
```toml
21+
[project]
22+
name = "mypackage"
23+
dynamic = ["version"]
24+
25+
[tool.scikit-build]
26+
metadata.version.provider = "scikit_build_core.metadata.setuptools_scm"
27+
sdist.include = ["src/package/_version.py"]
28+
29+
[tool.setuptools_scm] # Section required
30+
write_to = "src/package/_version.py"
31+
```
32+
33+
This sets the python project version according to
34+
[git tags](https://github.com/pypa/setuptools-scm/blob/fb261332d9b46aa5a258042d85baa5aa7b9f4fa2/README.rst#default-versioning-scheme)
35+
or a
36+
[`.git_archival.txt`](https://github.com/pypa/setuptools-scm/blob/fb261332d9b46aa5a258042d85baa5aa7b9f4fa2/README.rst#git-archives)
37+
file, or equivalents for other VCS systems.
38+
39+
If you need to set the CMake project version without scikit-build-core (which
40+
provides `${SKBUILD_PROJECT_VERSION}`), you can use something like
41+
[`DynamicVersion` module](https://github.com/LecrisUT/CMakeExtraUtils/blob/180604da50a3c3588f9d04e4ebc6abb4e5a0d234/cmake/DynamicVersion.md)
42+
from
43+
[github.com/LecrisUT/CMakeExtraUtils](https://github.com/LecrisUT/CMakeExtraUtils):
44+
45+
```cmake
46+
# Import `CMakeExtraUtils` or bundle `DynamicVersion.cmake` from there
47+
include(DynamicVersion)
48+
49+
# Set ${PROJECT_VERSION} according to git tag or `.git_archival.txt`
50+
dynamic_version()
51+
52+
project(MyPackage VERSION ${PROJECT_VERSION})
53+
```
54+
55+
## `version`: Regex
56+
57+
If you want to pull a string-valued expression (usually version) from an
58+
existing file, you can the integrated `regex` plugin to pull the information.
59+
60+
```toml
61+
name = "mypackage"
62+
dynamic = ["version"]
63+
64+
[tool.scikit-build.metadata.version]
65+
provider = "scikit_build_core.metadata.regex"
66+
input = "src/mypackage/__init__.py"
67+
```
68+
69+
You can set a custom regex with `regex=`. By default when targeting version, you
70+
get a reasonable regex for python files,
71+
`'(?i)^(__version__|VERSION)(?: ?\: ?str)? *= *([\'"])v?(?P<value>.+?)\2'`. You
72+
can set `result` to a format string to process the matches; the default is
73+
`"{value}"`. You can also specify a regex for `remove=` which will strip any
74+
matches from the final result. A more complex example:
75+
76+
```toml
77+
[tool.scikit-build.metadata.version]
78+
provider = "scikit_build_core.metadata.regex"
79+
input = "src/mypackage/version.hpp"
80+
regex = '''(?sx)
81+
\#define \s+ VERSION_MAJOR \s+ (?P<major>\d+) .*?
82+
\#define \s+ VERSION_MINOR \s+ (?P<minor>\d+) .*?
83+
\#define \s+ VERSION_PATCH \s+ (?P<patch>\d+) .*?
84+
\#define \s+ VERSION_DEV \s+ (?P<dev>\d+) .*?
85+
'''
86+
result = "{major}.{minor}.{patch}dev{dev}"
87+
remove = "dev0"
88+
```
89+
90+
This will remove the "dev" tag when it is equal to 0.
91+
92+
```{versionchanged} 0.10
93+
94+
Support for `result` and `remove` added.
95+
96+
```
97+
98+
## `readme`: Fancy-pypi-readme
99+
100+
You can use
101+
[hatch-fancy-pypi-readme](https://github.com/hynek/hatch-fancy-pypi-readme) to
102+
render your README:
103+
104+
```toml
105+
[project]
106+
name = "mypackage"
107+
dynamic = ["readme"]
108+
109+
[tool.scikit-build]
110+
metadata.readme.provider = "scikit_build_core.metadata.fancy_pypi_readme"
111+
112+
# tool.hatch.metadata.hooks.fancy-pypi-readme options here
113+
```
114+
115+
## Generate files with dynamic metadata
116+
117+
You can write out metadata to file(s) as well. Other info might become available
118+
here in the future, but currently it supports anything available as strings in
119+
metadata. (Note that arrays like this are only supported in TOML configuration.)
120+
121+
```toml
122+
[[tool.scikit-build.generate]]
123+
path = "package/_version.py"
124+
template = '''
125+
version = "${version}"
126+
'''
127+
```
128+
129+
`template` or `template-path` is required; this uses {class}`string.Template`
130+
formatting. There are three options for output location; `location = "install"`
131+
(the default) will go to the wheel, `location = "build"` will go to the CMake
132+
build directory, and `location = "source"` will write out to the source
133+
directory (be sure to .gitignore this file. It will automatically be added to
134+
your SDist includes. It will overwrite existing files).
135+
136+
The path is generally relative to the base of the wheel / build dir / source
137+
dir, depending on which location you pick.

‎docs/configuration.md‎ renamed to ‎docs/configuration/index.md‎

Lines changed: 0 additions & 144 deletions
Original file line numberDiff line numberDiff line change
@@ -539,150 +539,6 @@ You can pass raw arguments directly to the build tool, as well:
539539
540540
```
541541

542-
## Dynamic metadata
543-
544-
Scikit-build-core supports dynamic metadata with three built-in plugins.
545-
546-
:::{tab} Setuptools-scm
547-
548-
You can use [setuptools-scm](https://github.com/pypa/setuptools-scm) to pull the
549-
version from VCS:
550-
551-
```toml
552-
[project]
553-
name = "mypackage"
554-
dynamic = ["version"]
555-
556-
[tool.scikit-build]
557-
metadata.version.provider = "scikit_build_core.metadata.setuptools_scm"
558-
sdist.include = ["src/package/_version.py"]
559-
560-
[tool.setuptools_scm] # Section required
561-
write_to = "src/package/_version.py"
562-
```
563-
564-
This sets the python project version according to
565-
[git tags](https://github.com/pypa/setuptools-scm/blob/fb261332d9b46aa5a258042d85baa5aa7b9f4fa2/README.rst#default-versioning-scheme)
566-
or a
567-
[`.git_archival.txt`](https://github.com/pypa/setuptools-scm/blob/fb261332d9b46aa5a258042d85baa5aa7b9f4fa2/README.rst#git-archives)
568-
file, or equivalents for other VCS systems.
569-
570-
If you need to set the CMake project version without scikit-build-core (which
571-
provides `${SKBUILD_PROJECT_VERSION}`), you can use something like
572-
[`DynamicVersion` module](https://github.com/LecrisUT/CMakeExtraUtils/blob/180604da50a3c3588f9d04e4ebc6abb4e5a0d234/cmake/DynamicVersion.md)
573-
from
574-
[github.com/LecrisUT/CMakeExtraUtils](https://github.com/LecrisUT/CMakeExtraUtils):
575-
576-
```cmake
577-
# Import `CMakeExtraUtils` or bundle `DynamicVersion.cmake` from there
578-
include(DynamicVersion)
579-
580-
# Set ${PROJECT_VERSION} according to git tag or `.git_archival.txt`
581-
dynamic_version()
582-
583-
project(MyPackage VERSION ${PROJECT_VERSION})
584-
```
585-
586-
:::
587-
588-
:::{tab} Fancy-pypi-readme
589-
590-
You can use
591-
[hatch-fancy-pypi-readme](https://github.com/hynek/hatch-fancy-pypi-readme) to
592-
render your README:
593-
594-
```toml
595-
[project]
596-
name = "mypackage"
597-
dynamic = ["readme"]
598-
599-
[tool.scikit-build]
600-
metadata.readme.provider = "scikit_build_core.metadata.fancy_pypi_readme"
601-
602-
# tool.hatch.metadata.hooks.fancy-pypi-readme options here
603-
```
604-
605-
:::
606-
607-
:::{tab} Regex
608-
609-
If you want to pull a string-valued expression (usually version) from an
610-
existing file, you can the integrated `regex` plugin to pull the information.
611-
612-
```toml
613-
name = "mypackage"
614-
dynamic = ["version"]
615-
616-
[tool.scikit-build.metadata.version]
617-
provider = "scikit_build_core.metadata.regex"
618-
input = "src/mypackage/__init__.py"
619-
```
620-
621-
You can set a custom regex with `regex=`. By default when targeting version, you
622-
get a reasonable regex for python files,
623-
`'(?i)^(__version__|VERSION)(?: ?\: ?str)? *= *([\'"])v?(?P<value>.+?)\2'`. You
624-
can set `result` to a format string to process the matches; the default is
625-
`"{value}"`. You can also specify a regex for `remove=` which will strip any
626-
matches from the final result. A more complex example:
627-
628-
```toml
629-
[tool.scikit-build.metadata.version]
630-
provider = "scikit_build_core.metadata.regex"
631-
input = "src/mypackage/version.hpp"
632-
regex = '''(?sx)
633-
\#define \s+ VERSION_MAJOR \s+ (?P<major>\d+) .*?
634-
\#define \s+ VERSION_MINOR \s+ (?P<minor>\d+) .*?
635-
\#define \s+ VERSION_PATCH \s+ (?P<patch>\d+) .*?
636-
\#define \s+ VERSION_DEV \s+ (?P<dev>\d+) .*?
637-
'''
638-
result = "{major}.{minor}.{patch}dev{dev}"
639-
remove = "dev0"
640-
```
641-
642-
This will remove the "dev" tag when it is equal to 0.
643-
644-
::::{versionchanged} 0.10
645-
646-
Support for `result` and `remove` added.
647-
648-
::::
649-
650-
:::
651-
652-
:::{warning}
653-
654-
Your package and third-party packages can also extend these with new plugins,
655-
but this is currently not ready for development outside of scikit-build-core;
656-
`tool.scikit-build.experimental=true` is required to use plugins that are not
657-
shipped with scikit-build-core, since the interface is provisional and may
658-
change between _minor_ versions.
659-
660-
:::
661-
662-
### Writing metadata
663-
664-
You can write out metadata to file(s) as well. Other info might become available
665-
here in the future, but currently it supports anything available as strings in
666-
metadata. (Note that arrays like this are only supported in TOML configuration.)
667-
668-
```toml
669-
[[tool.scikit-build.generate]]
670-
path = "package/_version.py"
671-
template = '''
672-
version = "${version}"
673-
'''
674-
```
675-
676-
`template` or `template-path` is required; this uses {class}`string.Template`
677-
formatting. There are three options for output location; `location = "install"`
678-
(the default) will go to the wheel, `location = "build"` will go to the CMake
679-
build directory, and `location = "source"` will write out to the source
680-
directory (be sure to .gitignore this file. It will automatically be added to
681-
your SDist includes. It will overwrite existing files).
682-
683-
The path is generally relative to the base of the wheel / build dir / source
684-
dir, depending on which location you pick.
685-
686542
## Editable installs
687543

688544
Experimental support for editable installs is provided, with some caveats and

‎docs/overrides.md‎ renamed to ‎docs/configuration/overrides.md‎

File renamed without changes.

‎docs/build.md‎ renamed to ‎docs/guide/build.md‎

File renamed without changes.

‎docs/cmakelists.md‎ renamed to ‎docs/guide/cmakelists.md‎

File renamed without changes.

‎docs/crosscompile.md‎ renamed to ‎docs/guide/crosscompile.md‎

File renamed without changes.

‎docs/faqs.md‎ renamed to ‎docs/guide/faqs.md‎

File renamed without changes.

0 commit comments

Comments
 (0)