Merge pull request #52 from python-project-templates/tkp/docs

Add more documentation

Author: timkpaine

README.md

@@ -23,15 +23,77 @@ For more complete systems, see:
 - [scikit-build-core](https://github.com/scikit-build/scikit-build-core)
 - [setuptools](https://setuptools.pypa.io/en/latest/userguide/ext_modules.html)
 
-## Environment Variables
-
-| Name                       | Default | Description |
-| :------------------------- | :------ | :---------- |
-| `CC`                       |         |             |
-| `CXX`                      |         |             |
-| `LD`                       |         |             |
-| `HATCH_CPP_PLATFORM`       |         |             |
-| `HATCH_CPP_DISABLE_CCACHE` |         |             |
+## Configuration
+
+Configuration is driven from the `[tool.hatch.build.hooks.hatch-cpp]` hatch hook configuration field in a `pyproject.toml`.
+It is designed to closely match existing Python/C/C++ packaging tools.
+
+```toml
+verbose = true
+libraries = { Library Args }
+cmake = { CMake Args }
+platform = { Platform, either "linux", "darwin", or "win32" }
+```
+
+See the [test cases](./hatch_cpp/tests/) for more concrete examples.
+
+`hatch-cpp` is driven by [pydantic](https://docs.pydantic.dev/latest/) models for configuration and execution of the build.
+These models can themselves be overridden by setting `build-config-class` / `build-plan-class`.
+
+### Library Arguments
+
+```toml
+name = "mylib"
+sources = [
+    "path/to/file.cpp",
+]
+language = "c++"
+
+binding = "cpython" # or "pybind11", "nanobind", "generic"
+std = "" # Passed to -std= or /std:
+
+include_dirs = ["paths/to/add/to/-I"]
+library_dirs = ["paths/to/add/to/-L"]
+libraries = ["-llibraries_to_link"]
+
+extra_compile_args = ["--extra-compile-args"]
+extra_link_args = ["--extra-link-args"]
+extra_objects = ["extra_objects"]
+
+define_macros = ["-Ddefines_to_use"]
+undef_macros = ["-Uundefines_to_use"]
+
+py_limited_api = "cp39"  # limited API to use
+```
+
+### CMake Arguments
+
+`hatch-cpp` has some convenience integration with CMake.
+Though this is not designed to be as full-featured as e.g. `scikit-build`, it should be satisfactory for many small projects.
+
+```toml
+root = "path/to/cmake/root"
+build = "path/to/cmake/build/folder"
+install = "path/to/cmake/install/folder"
+
+cmake_arg_prefix = "MYPROJECT_"
+cmake_args = {}  # any other cmake args to pass
+cmake_env_args = {} # env-specific cmake args to pass
+
+include_flags = {} # include flags to pass -D
+```
+
+### Environment Variables
+
+`hatch-cpp` will respect standard environment variables for compiler control.
+
+| Name                       | Default | Description           |
+| :------------------------- | :------ | :-------------------- |
+| `CC`                       |         | C Compiler override   |
+| `CXX`                      |         | C++ Compiler override |
+| `LD`                       |         | Linker override       |
+| `HATCH_CPP_PLATFORM`       |         | Platform to build     |
+| `HATCH_CPP_DISABLE_CCACHE` |         | Disable CCache usage  |
 
 > [!NOTE]
 > This library was generated using [copier](https://copier.readthedocs.io/en/stable/) from the [Base Python Project Template repository](https://github.com/python-project-templates/base).