Update documentation

docs/build.md

@@ -2,7 +2,7 @@
 
 -----
 
-Before building your application, you must configure your [project](config.md#project) at the very least.
+Before building your application, you must configure your [project](config/project.md) at the very least.
 
 After you have done that, your application can be built using a [local copy](#local-repository) of this repository or via [installation](#installation) with Cargo.
 
@@ -49,4 +49,4 @@ Specific versions may be chosen with the `--version` flag.
 
 Configuration for [cross](https://github.com/cross-rs/cross) is validated by CI to ensure all known environment variable options are passed through to the containers.
 
-When embedding the [project](config.md#project-embedding) or the [distribution](config.md#distribution-embedding) using a local path, you must use the [local repository](#local-repository) way of building and ensure that the configured files to embed reside within the repository and the options refer to relative paths.
+When embedding the [project](config/project.md#embedding) or the [distribution](config/distribution.md#embedding) using a local path, you must use the [local repository](#local-repository) way of building and ensure that the configured files to embed reside within the repository and the options refer to relative paths.

docs/config/cli.md

@@ -0,0 +1,46 @@
+# Command line configuration
+
+-----
+
+## Installation indicator
+
+The environment variable that is used for [detection](../runtime.md#detection) may be set to the path of the executable at runtime if you set the `PYAPP_PASS_LOCATION` option to `true` or `1`. This is useful if your application wishes to in some way manage itself.
+
+## Management command
+
+You may set the `PYAPP_SELF_COMMAND` option to override the default name (`self`) of the [management command group](../runtime.md#commands). Setting this to `none` effectively disables the use of management commands.
+
+When enabled, the value will be available at runtime as the `PYAPP_COMMAND_NAME` environment variable.
+
+## Metadata template
+
+You may set a custom template used to [output metadata](../runtime.md#metadata) with the `PYAPP_METADATA_TEMPLATE` option which supports the following placeholders:
+
+| Placeholder | Description |
+| --- | --- |
+| `{project}` | The normalized project name |
+| `{version}` | The currently installed version of the project |
+
+The default template is `{project} v{version}` if this option is unset.
+
+This is useful for setting [custom commands](https://starship.rs/config/#custom-commands) for the [Starship](https://github.com/starship/starship) prompt. The following example configuration assumes that the built executable has been renamed to `foo`:
+
+````toml
+format = """
+...
+${custom.foo}\
+...
+$line_break\
+...
+$character"""
+
+# <clipped>
+
+[custom.foo]
+command = "foo self metadata"
+when = true
+## Windows
+# shell = ["cmd", "/C"]
+## Other
+# shell = ["sh", "--norc"]
+````

docs/config/distribution.md

@@ -0,0 +1,75 @@
+# Python distribution configuration
+
+-----
+
+## Known
+
+Setting the `PYAPP_PYTHON_VERSION` option will determine the distribution used at runtime based on the environment at build time. If unset then the default will be the latest stable minor version of [CPython](#cpython).
+
+### CPython
+
+| ID |
+| --- |
+| `3.7` |
+| `3.8` |
+| `3.9` |
+| `3.10` |
+| `3.11` |
+| `3.12` |
+
+The source for pre-built distributions is the [python-build-standalone](https://github.com/indygreg/python-build-standalone) project.
+
+Some distributions have [variants](https://gregoryszorc.com/docs/python-build-standalone/main/running.html) that may be configured with the `PYAPP_DISTRIBUTION_VARIANT` option:
+
+| Platform | Options |
+| --- | --- |
+| Linux | <ul><li><code>v1</code></li><li><code>v2</code></li><li><code>v3</code> (default)</li><li><code>v4</code></li></ul> |
+
+### PyPy
+
+| ID |
+| --- |
+| `pypy2.7` |
+| `pypy3.9` |
+| `pypy3.10` |
+
+The source of distributions is the [PyPy](https://www.pypy.org) project.
+
+## Custom
+
+You may explicitly set the `PYAPP_DISTRIBUTION_SOURCE` option which overrides the [known](#known) distribution settings. The source must be a URL that points to an archived version of the desired Python distribution.
+
+Setting this manually may require you to define extra metadata about the distribution that is required for correct [runtime behavior](../runtime.md).
+
+### Format
+
+The following formats are supported for the `PYAPP_DISTRIBUTION_FORMAT` option, with the default chosen based on the ending of the source URL:
+
+| Format | Extensions | Description |
+| --- | --- | --- |
+| `tar|bzip2` | <ul><li><code>.tar.bz2</code></li><li><code>.bz2</code></li></ul> | A [tar file](https://en.wikipedia.org/wiki/Tar_(computing)) with [bzip2 compression](https://en.wikipedia.org/wiki/Bzip2) |
+| `tar|gzip` | <ul><li><code>.tar.gz</code></li><li><code>.tgz</code></li></ul> | A [tar file](https://en.wikipedia.org/wiki/Tar_(computing)) with [gzip compression](https://en.wikipedia.org/wiki/Gzip) |
+| `tar|zstd` | <ul><li><code>.tar.zst</code></li><li><code>.tar.zstd</code></li></ul> | A [tar file](https://en.wikipedia.org/wiki/Tar_(computing)) with [Zstandard compression](https://en.wikipedia.org/wiki/Zstd) |
+| `zip` | <ul><li><code>.zip</code></li></ul> | A [ZIP file](https://en.wikipedia.org/wiki/ZIP_(file_format)) with [DEFLATE compression](https://en.wikipedia.org/wiki/Deflate) |
+
+### Python location
+
+You may set the relative path to the Python executable after unpacking the archive with the `PYAPP_DISTRIBUTION_PYTHON_PATH` option. The default is `python.exe` on Windows and `bin/python3` on all other platforms.
+
+### Site packages location
+
+You may set the relative path to the [`site-packages`](https://docs.python.org/3/library/site.html) directory after unpacking the archive with the `PYAPP_DISTRIBUTION_SITE_PACKAGES_PATH` option. The default is `Lib\site-packages` on Windows and `lib/python<ID>/site-packages` on all other platforms where `<ID>` is the defined [distribution ID](#known).
+
+### pip availability
+
+You may indicate whether pip is already installed by setting the `PYAPP_DISTRIBUTION_PIP_AVAILABLE` option to `true` or `1`. This elides the check for installation when [upgraded virtual environments](installation.md#virtual-environments) are enabled.
+
+## Embedding
+
+You may set the `PYAPP_DISTRIBUTION_EMBED` option to `true` or `1` to embed the distribution in the executable at build time to avoid fetching it at runtime.
+
+You can set the `PYAPP_DISTRIBUTION_PATH` option to use a local path rather than fetching the source, which implicitly enables embedding. The local archive should be similar to the [default distributions](#known) in that there should be a Python interpreter ready for use.
+
+## Full isolation
+
+You may set the `PYAPP_FULL_ISOLATION` option to `true` or `1` to provide each installation with a full copy of the distribution rather than a virtual environment.