Add long-form docs on configuration options

[jameslamb]

Description

The table in the README listing configuration options is useful to see what's available at a glance. It's also a great way to get an idea of what types of concerns rapids-build-backend is meant to address.

But the table format is really limiting... putting more than a few words describing a given configuration option would reduce the visual usefulness of the table fast (since it would grow the how table vertically).

At some point, I think it'd be useful to write dedicated documentation with long-form descriptions covering the following for each configuration option:

• what are the valid values?
• when might you want to override the default?
• how do the options relate to each other?

Benefits of this work

Improves the likelihood that someone building with this backend could be productive on their own.

Acceptance Criteria

• long form docs exist for all the config options

Approach

I am thinking something like a docs/config.rst, with content similar to this:

commit-file
'''''''''''''''''''

``rapids-build-backend`` automatically records the current git commit for the source tree it's building from, and writes that to a text file bundled into the wheel.

By default, that will be in a file `{[project].name}/GIT_COMMIT`. For example, given a `pyproject.toml` like this:

[project]
name = "sparkly-unicorn"

rapids-build-backend will write out that commit sha to a location ``./sparkly_unicorn/GIT_COMMIT``, relative to wherever that ``pyproject.toml`` file is.

Provide some other relative path here to override that behavior and tell it to write to a custom location.

I think it'd be fine for that to just live in a file in this repo. This issue could be considered "done", in my opinion, without setting up any docs rendering or hosting.

Some good references for this:

• https://scikit-build-core.readthedocs.io/en/latest/configuration.html
• https://setuptools.pypa.io/en/latest/userguide/datafiles.html

Notes

N/A

[vyasr]

I agree, some documentation would be good. I think it's probably worthwhile to wait until we stabilize a bit more, though, since we are currently in a decent amount of flux.