Refactor DCDoc usage

- Moved default text handling to a separate function
- Prepare to read metadata fields from dataclasses.Field.metadata
- Added a dataclass holder for the dataclass field metadata for documentation

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

Author: LecrisUT

src/scikit_build_core/settings/documentation.py

@@ -5,7 +5,7 @@
 import inspect
 import textwrap
 from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, TypeVar, cast
 
 from packaging.specifiers import SpecifierSet
 from packaging.version import Version
@@ -15,6 +15,10 @@
 if TYPE_CHECKING:
     from collections.abc import Generator
 
+T = TypeVar("T")
+U = TypeVar("U")
+
+
 __all__ = ["pull_docs"]
 
 
@@ -56,6 +60,19 @@ def __str__(self) -> str:
         return f"{docs}\n{self.name} = {self.default}\n"
 
 
+def get_metadata_field(field: dataclasses.Field[U], field_name: str, default: T) -> T:
+    if field_name in field.metadata:
+        return cast("T", field.metadata[field_name])
+    return default
+
+
+def sanitize_default_field(text: str) -> str:
+    text = text.replace("'", '"')
+    text = text.replace("True", "true")
+    text = text.replace("False", "false")
+    return text  # noqa: RET504
+
+
 def mk_docs(dc: type[object], prefix: str = "") -> Generator[DCDoc, None, None]:
     """
     Makes documentation for a dataclass.
@@ -87,7 +104,7 @@ def mk_docs(dc: type[object], prefix: str = "") -> Generator[DCDoc, None, None]:
             default = '""'
 
         yield DCDoc(
-            f"{prefix}{field.name}".replace("_", "-"),
-            default.replace("'", '"').replace("True", "true").replace("False", "false"),
-            docs[field.name],
+            name=f"{prefix}{field.name}".replace("_", "-"),
+            default=sanitize_default_field(default),
+            docs=docs[field.name],
         )

src/scikit_build_core/settings/skbuild_model.py

@@ -1,4 +1,5 @@
 import dataclasses
+from collections.abc import Iterator, Mapping
 from pathlib import Path
 from typing import Any, Dict, List, Literal, Optional, Union
 
@@ -29,6 +30,23 @@ def __dir__() -> List[str]:
     return __all__
 
 
+@dataclasses.dataclass
+class SettingsFieldMetadata(Mapping[str, Any]):
+    """
+    Convenience dataclass to store field metadata for documentation.
+    """
+
+    def __getitem__(self, key: str) -> Any:
+        return getattr(self, key)
+
+    def __len__(self) -> int:
+        return len(dataclasses.fields(self))
+
+    def __iter__(self) -> Iterator[str]:
+        for field in dataclasses.fields(self):
+            yield field.name
+
+
 class CMakeSettingsDefine(str):
     """
     A str subtype for automatically normalizing bool and list values