Document formattable fields

Signed-off-by: Cristian Le <[email protected]>

Author: LecrisUT

docs/configuration/formatted.md

@@ -0,0 +1,27 @@
+# Formattable fields
+
+The following configure keys are formatted as Python f-strings:
+
+- `build-dir`
+- `build.requires`
+
+The available variables are documented in the members of
+{py:class}`scikit_build_core.format.PyprojectFormatter` copied here for
+visibility
+
+```{eval-rst}
+.. autoattribute:: scikit_build_core.format.PyprojectFormatter.build_type
+   :no-index:
+
+.. autoattribute:: scikit_build_core.format.PyprojectFormatter.cache_tag
+   :no-index:
+
+.. autoattribute:: scikit_build_core.format.PyprojectFormatter.root
+   :no-index:
+
+.. autoattribute:: scikit_build_core.format.PyprojectFormatter.state
+   :no-index:
+
+.. autoattribute:: scikit_build_core.format.PyprojectFormatter.wheel_tag
+   :no-index:
+```

docs/configuration/index.md

@@ -643,13 +643,8 @@ speedups.
 
 ```
 
-There are several values you can access through Python's formatting syntax:
-
-- `cache_tag`: `sys.implementation.cache_tag`
-- `wheel_tag`: The tags as computed for the wheel
-- `build_type`: The current build type (`Release` by default)
-- `state`: The current run state, `sdist`, `wheel`, `editable`,
-  `metadata_wheel`, and `metadata_editable`
+There are several values you can access through Python's formatting syntax. See
+[](./formatted.md).
 
 Scikit-build-core also strictly validates configuration; if you need to disable
 this, you can:

docs/index.md

@@ -43,6 +43,7 @@ guide/faqs
 configuration/index
 configuration/overrides
 configuration/dynamic
+configuration/formatted
 ```
 
 ```{toctree}

src/scikit_build_core/format.py

@@ -32,10 +32,15 @@ class PyprojectFormatter(TypedDict, total=False):
     """
 
     cache_tag: str
+    """Tag used by the import machinery in the filenames of cached modules, i.e. ``sys.implementation.cache_tag``."""
     wheel_tag: str
+    """The tags as computed for the wheel."""
     build_type: str
-    state: str
+    """Build type passed as ``cmake.build_type``."""
+    state: Literal["sdist", "wheel", "editable", "metadata_wheel", "metadata_editable"]
+    """The state of the build."""
     root: RootPathResolver
+    """Root path of the current project."""
 
 
 def pyproject_format(