From 4985489fbd11f81e7ad981bd2476464c39410a3c Mon Sep 17 00:00:00 2001 From: Ofek Lev Date: Sun, 21 Apr 2024 13:16:57 -0400 Subject: [PATCH] Update documentation --- docs/build.md | 4 +- docs/config.md | 225 ------------------------------------ docs/config/cli.md | 46 ++++++++ docs/config/distribution.md | 75 ++++++++++++ docs/config/installation.md | 52 +++++++++ docs/config/project.md | 65 +++++++++++ docs/examples.md | 2 +- docs/how-to.md | 2 +- docs/runtime.md | 40 +++---- hatch.toml | 11 +- mkdocs.yml | 9 +- 11 files changed, 274 insertions(+), 257 deletions(-) delete mode 100644 docs/config.md create mode 100644 docs/config/cli.md create mode 100644 docs/config/distribution.md create mode 100644 docs/config/installation.md create mode 100644 docs/config/project.md diff --git a/docs/build.md b/docs/build.md index 5900122..e367164 100644 --- a/docs/build.md +++ b/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. diff --git a/docs/config.md b/docs/config.md deleted file mode 100644 index 103e874..0000000 --- a/docs/config.md +++ /dev/null @@ -1,225 +0,0 @@ -# Configuration - ------ - -All configuration is done with environment variables. - -## Project - -There are 3 ways to configure runtime installation, none of which will occur when [disabled](#skipping-project-installation). - -The project name and version must be known in all cases. - -### Package index - -The desired project name and version are configured with the `PYAPP_PROJECT_NAME` and `PYAPP_PROJECT_VERSION` options, respectively. The project name must adhere to [PEP 508](https://peps.python.org/pep-0508/#names) and will be normalized during builds according to [PEP 503](https://peps.python.org/pep-0503/#normalized-names). - -#### Dependency file - -You may install your project using a dependency file with the `PYAPP_PROJECT_DEPENDENCY_FILE` option which should be a local path to the file. In this mode, the project name and version have nothing to do with installation and are just used as metadata. - -The following formats are supported: - -| Extensions | Description | -| --- | --- | -| .txt
.in | This is the [requirements file format](https://pip.pypa.io/en/stable/reference/requirements-file-format/) | - -### Embedding ### {: #project-embedding } - -You may embed the project with the `PYAPP_PROJECT_PATH` option which should be a path to a wheel ending in `.whl` or a source distribution ending in `.tar.gz`. - -!!! note - The project name and version is automatically derived from the metadata files inside. - -## Features (extras) ## {: #project-features } - -You may set the `PYAPP_PROJECT_FEATURES` option to select [optional dependency groups](https://packaging.python.org/en/latest/specifications/dependency-specifiers/#extras) that would usually be passed to installers within square brackets after the package name e.g. `pkg[foo,bar]`. In that example, you would set `PYAPP_PROJECT_FEATURES` to `foo,bar`. - -This also works when [embedding the project](#project-embedding). - -## Execution mode - -The following options are mutually exclusive: - -| Option | Description | -| --- | --- | -| `PYAPP_EXEC_MODULE` | This is the name of the module to execute via `python -m ` | -| `PYAPP_EXEC_SPEC` | This is an [object reference](https://packaging.python.org/en/latest/specifications/entry-points/#data-model) to execute e.g. `pkg.foo:cli` | -| `PYAPP_EXEC_CODE` | This is arbitrary code to run via `python -c ` (the spec option uses this internally) | -| `PYAPP_EXEC_SCRIPT` | This is a path to a script to embed in the binary and run | -| `PYAPP_EXEC_NOTEBOOK` | This is a path to a [Jupyter notebook](https://docs.jupyter.org/en/latest/) (`.ipynb` file) to embed in the binary and run | - -If none are set then the `PYAPP_EXEC_MODULE` option will default to the value of `PYAPP_PROJECT_NAME` with hyphens replaced by underscores. - -### GUI - -If you are packaging a graphical user interface (GUI), you can set `PYAPP_IS_GUI` to `true` or `1`. - -On Windows, this will use `pythonw.exe` instead of `python.exe` to execute [the application](https://docs.python.org/3/using/windows.html#python-application), which avoids a console window from appearing. Running a GUI application with `pythonw.exe` means that all `stdout` and `stderr` output from your GUI will be discarded. - -Otherwise, the application will execute as usual. PyApp will run your GUI by spawning a new process, such that the console window that runs the application terminates after successful spawning. - -Even when `PYAPP_IS_GUI` is enabled you can still run the application from the command line. Furthermore, PyApp-specific logic (e.g. installation and setup) will still display a console window with status messages. - -!!! note - On macOS, the console by default does not automatically close when processes have terminated (however it can be closed manually without interferring with the GUI). The default console behavior [can be changed](https://stackoverflow.com/questions/5560167/osx-how-to-auto-close-terminal-window-after-the-exit-command-executed) in the user settings to close after the last process terminates successfully. - -## Python distribution - -### 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 |
  • v1
  • v2
  • v3 (default)
  • v4
| - -#### 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` |
  • .tar.bz2
  • .bz2
| A [tar file](https://en.wikipedia.org/wiki/Tar_(computing)) with [bzip2 compression](https://en.wikipedia.org/wiki/Bzip2) | -| `tar|gzip` |
  • .tar.gz
  • .tgz
| A [tar file](https://en.wikipedia.org/wiki/Tar_(computing)) with [gzip compression](https://en.wikipedia.org/wiki/Gzip) | -| `tar|zstd` |
  • .tar.zst
  • .tar.zstd
| A [tar file](https://en.wikipedia.org/wiki/Tar_(computing)) with [Zstandard compression](https://en.wikipedia.org/wiki/Zstd) | -| `zip` |
  • .zip
| 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/site-packages` on all other platforms where `` is the [distribution ID](#known) is defined. - -#### 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](#virtual-environments) are enabled. - -### Embedding ### {: #distribution-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](#python-distribution) in that there should be a Python interpreter ready for use. - -## UV - -You may set the `PYAPP_UV_ENABLED` option to `true` or `1` to use [UV](https://github.com/astral-sh/uv) for virtual environment creation and project installation. - -### Version ### {: #uv-version } - -You may use a specific `X.Y.Z` version by setting the `PYAPP_UV_VERSION` option. - -By default, a version of UV that has already been downloaded by a PyApp application is used. If UV has not yet been downloaded then the latest version is used. - -### Only bootstrap - -You may set the `PYAPP_UV_ONLY_BOOTSTRAP` option to `true` or `1` to only use UV for virtual environment creation and continue using pip for project installation. - -## pip - -These options have no effect when the project installation is [disabled](#skipping-project-installation). - -### Externally managed - -You may set the `PYAPP_PIP_EXTERNAL` option to `true` or `1` to use the [standalone](https://pip.pypa.io/en/stable/installation/#standalone-zip-application) versions of pip rather than whatever the distribution provides. - -By default, the latest version is used. You may use a specific `X.Y.Z` version by setting the `PYAPP_PIP_VERSION` option. - -!!! tip - This provides a significant installation speed up when [full isolation](#full-isolation) is not enabled. - -### Extra arguments - -You may set the `PYAPP_PIP_EXTRA_ARGS` option to provide extra arguments to the [`pip install`](https://pip.pypa.io/en/stable/cli/pip_install/) command at runtime when installing or updating the project e.g. `--only-binary :all: --index-url URL`. - -### Allowing configuration - -You may set the `PYAPP_PIP_ALLOW_CONFIG` option to `true` or `1` to allow the use of environment variables and other configuration at runtime. - -## 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. - -## Virtual environments - -When [full isolation](#full-isolation) is not enabled, you may set the `PYAPP_UPGRADE_VIRTUALENV` option to `true` or `1` to create virtual environments with [virtualenv](https://github.com/pypa/virtualenv) rather than the standard library's `venv` module. - -## Skipping project installation - -You may set the `PYAPP_SKIP_INSTALL` option to `true` or `1` to skip installing the project in the distribution. This allows for entirely predefined distributions and thus no network calls at runtime if used in conjunction with [distribution embedding](#distribution-embedding). - -## 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""" - -# - -[custom.foo] -command = "foo self metadata" -when = true -## Windows -# shell = ["cmd", "/C"] -## Other -# shell = ["sh", "--norc"] -```` diff --git a/docs/config/cli.md b/docs/config/cli.md new file mode 100644 index 0000000..b8d41bf --- /dev/null +++ b/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""" + +# + +[custom.foo] +command = "foo self metadata" +when = true +## Windows +# shell = ["cmd", "/C"] +## Other +# shell = ["sh", "--norc"] +```` diff --git a/docs/config/distribution.md b/docs/config/distribution.md new file mode 100644 index 0000000..ba20dd0 --- /dev/null +++ b/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 |
  • v1
  • v2
  • v3 (default)
  • v4
| + +### 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` |
  • .tar.bz2
  • .bz2
| A [tar file](https://en.wikipedia.org/wiki/Tar_(computing)) with [bzip2 compression](https://en.wikipedia.org/wiki/Bzip2) | +| `tar|gzip` |
  • .tar.gz
  • .tgz
| A [tar file](https://en.wikipedia.org/wiki/Tar_(computing)) with [gzip compression](https://en.wikipedia.org/wiki/Gzip) | +| `tar|zstd` |
  • .tar.zst
  • .tar.zstd
| A [tar file](https://en.wikipedia.org/wiki/Tar_(computing)) with [Zstandard compression](https://en.wikipedia.org/wiki/Zstd) | +| `zip` |
  • .zip
| 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/site-packages` on all other platforms where `` 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. diff --git a/docs/config/installation.md b/docs/config/installation.md new file mode 100644 index 0000000..027919e --- /dev/null +++ b/docs/config/installation.md @@ -0,0 +1,52 @@ +# Installation configuration + +----- + +These options have no effect when the project installation is [disabled](#skipping-installation). + +## UV + +You may set the `PYAPP_UV_ENABLED` option to `true` or `1` to use [UV](https://github.com/astral-sh/uv) for virtual environment creation and project installation. + +### Version ### {: #uv-version } + +You may use a specific `X.Y.Z` version by setting the `PYAPP_UV_VERSION` option. + +By default, a version of UV that has already been downloaded by a PyApp application is used. If UV has not yet been downloaded then the latest version is used. + +### Only bootstrap + +You may set the `PYAPP_UV_ONLY_BOOTSTRAP` option to `true` or `1` to only use UV for virtual environment creation and continue using pip for project installation. + +## pip + +These options have no effect when UV is [enabled](#uv). + +### Externally managed + +You may set the `PYAPP_PIP_EXTERNAL` option to `true` or `1` to use the [standalone](https://pip.pypa.io/en/stable/installation/#standalone-zip-application) versions of pip rather than whatever the distribution provides. + +By default, the latest version is used. You may use a specific `X.Y.Z` version by setting the `PYAPP_PIP_VERSION` option. + +!!! tip + This provides a significant installation speed up when [full isolation](distribution.md#full-isolation) is not enabled. + +### Allowing configuration + +You may set the `PYAPP_PIP_ALLOW_CONFIG` option to `true` or `1` to allow the use of environment variables and other configuration at runtime. + +### Virtual environments + +When [full isolation](distribution.md#full-isolation) is not enabled, you may set the `PYAPP_UPGRADE_VIRTUALENV` option to `true` or `1` to create virtual environments with [virtualenv](https://github.com/pypa/virtualenv) rather than the standard library's `venv` module. + +## Extra installer arguments + +You may set the `PYAPP_PIP_EXTRA_ARGS` option to provide extra arguments to the [`pip install`](https://pip.pypa.io/en/stable/cli/pip_install/) (or [UV](#uv) equivalent) command at runtime when installing or updating the project e.g. `--only-binary :all: --extra-index-url URL`. + +## Location + +The default location of your application's installation differs based on the operating system and can be overridden at runtime with the `PYAPP_INSTALL_DIR_` environment variable where `` is the uppercased version of the [project name](project.md#identifier). + +## Skipping installation + +You may set the `PYAPP_SKIP_INSTALL` option to `true` or `1` to skip installing the project in the distribution. This allows for entirely predefined distributions and thus no network calls at runtime if used in conjunction with [distribution embedding](distribution.md#embedding). diff --git a/docs/config/project.md b/docs/config/project.md new file mode 100644 index 0000000..b360172 --- /dev/null +++ b/docs/config/project.md @@ -0,0 +1,65 @@ +# Project configuration + +----- + +## Sources + +There are 3 ways to configure runtime installation, none of which will occur when [disabled](installation.md#skipping-installation). + +The project [identifier](#identifier) must be known in all cases. + +### Identifier + +The desired project name and version are configured with the `PYAPP_PROJECT_NAME` and `PYAPP_PROJECT_VERSION` options, respectively. The project name must adhere to [PEP 508](https://peps.python.org/pep-0508/#names) and will be normalized during builds according to [PEP 503](https://peps.python.org/pep-0503/#normalized-names). + +When using only this method, the package will be installed from a package index like PyPI. + +### Dependency file + +You may install your project using a dependency file with the `PYAPP_PROJECT_DEPENDENCY_FILE` option which should be a local path to the file. In this mode, the project [identifier](#identifier) has nothing to do with installation and is just used as metadata. + +The following formats are supported: + +| Extensions | Description | +| --- | --- | +| .txt
.in | This is the [requirements file format](https://pip.pypa.io/en/stable/reference/requirements-file-format/) | + +### Embedding + +You may embed the project with the `PYAPP_PROJECT_PATH` option which should be a path to a wheel ending in `.whl` or a source distribution ending in `.tar.gz`. + +!!! note + The project [identifier](#identifier) is automatically derived from the metadata files inside. + +## Features (extras) ## {: #features } + +You may set the `PYAPP_PROJECT_FEATURES` option to select [optional dependency groups](https://packaging.python.org/en/latest/specifications/dependency-specifiers/#extras) that would usually be passed to installers within square brackets after the package name e.g. `pkg[foo,bar]`. In that example, you would set `PYAPP_PROJECT_FEATURES` to `foo,bar`. + +This also works when [embedding the project](#embedding). + +## Execution mode + +The following options are mutually exclusive: + +| Option | Description | +| --- | --- | +| `PYAPP_EXEC_MODULE` | This is the name of the module to execute via `python -m ` | +| `PYAPP_EXEC_SPEC` | This is an [object reference](https://packaging.python.org/en/latest/specifications/entry-points/#data-model) to execute e.g. `pkg.foo:cli` | +| `PYAPP_EXEC_CODE` | This is arbitrary code to run via `python -c ` (the spec option uses this internally) | +| `PYAPP_EXEC_SCRIPT` | This is a path to a script to embed in the binary and run | +| `PYAPP_EXEC_NOTEBOOK` | This is a path to a [Jupyter notebook](https://docs.jupyter.org/en/latest/) (`.ipynb` file) to embed in the binary and run | + +If none are set then the `PYAPP_EXEC_MODULE` option will default to the value of `PYAPP_PROJECT_NAME` with hyphens replaced by underscores. + +### GUI + +If you are packaging a graphical user interface (GUI), you can set `PYAPP_IS_GUI` to `true` or `1`. + +On Windows, this will use `pythonw.exe` instead of `python.exe` to execute [the application](https://docs.python.org/3/using/windows.html#python-application), which avoids a console window from appearing. Running a GUI application with `pythonw.exe` means that all `stdout` and `stderr` output from your GUI will be discarded. + +Otherwise, the application will execute as usual. PyApp will run your GUI by spawning a new process, such that the console window that runs the application terminates after successful spawning. + +Even when `PYAPP_IS_GUI` is enabled you can still run the application from the command line. Furthermore, PyApp-specific logic (e.g. installation and setup) will still display a console window with status messages. + +!!! note + On macOS, the console by default does not automatically close when processes have terminated (however it can be closed manually without interferring with the GUI). The default console behavior [can be changed](https://stackoverflow.com/questions/5560167/osx-how-to-auto-close-terminal-window-after-the-exit-command-executed) in the user settings to close after the last process terminates successfully. diff --git a/docs/examples.md b/docs/examples.md index 51450eb..fa4d980 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -26,7 +26,7 @@ The following examples do not illustrate every possible combination of options b | `PYAPP_PROJECT_DEPENDENCY_FILE` | `./requirements.txt` | !!! note - The [default execution](config.md#execution-mode) will be `python -m proj` at runtime. + The [default execution](config/project.md#execution-mode) will be `python -m proj` at runtime. ## Dependency file with script diff --git a/docs/how-to.md b/docs/how-to.md index 908485a..cfdfcd7 100644 --- a/docs/how-to.md +++ b/docs/how-to.md @@ -26,7 +26,7 @@ In order to [build](build.md) applications with PyApp, you must first download t ## Configuration -You must [configure](config.md) the binaries PyApp produces with environment variables. There are [many ways](examples.md) to configure applications but here we will define a single package to install from PyPI at a specific version: +You must [configure](config/project.md) the binaries PyApp produces with environment variables. There are [many ways](examples.md) to configure applications but here we will define a single package to install from PyPI at a specific version: | Option | Value | | --- | --- | diff --git a/docs/runtime.md b/docs/runtime.md index fd49359..fa067f6 100644 --- a/docs/runtime.md +++ b/docs/runtime.md @@ -51,42 +51,38 @@ flowchart TD MNG -- Yes --> MNGCMD([Command invoked]) MNGCMD -- No --> EXECUTE MNGCMD -- Yes --> MANAGE[[Run management command]] - click DISTEMBEDDED href "../config/#distribution-embedding" - click FULLISOLATION href "../config/#full-isolation" - click UVENABLED href "../config/#uv" - click UVENABLEDUNPACK href "../config/#uv" - click EXTERNALPIP href "../config/#externally-managed" - click PROJEMBEDDED href "../config/#project-embedding" - click DEPFILE href "../config/#dependency-file" - click SINGLEPROJECT href "../config/#package-index" - click DEPFILEINSTALL href "../config/#dependency-file" - click PROJEMBED href "../config/#project-embedding" - click MNG href "../config/#management-command" - click MNGCMD href "../config/#management-command" + click DISTEMBEDDED href "../config/distribution/#embedding" + click FULLISOLATION href "../config/distribution/#full-isolation" + click UVENABLED href "../config/installation/#uv" + click UVENABLEDUNPACK href "../config/installation/#uv" + click EXTERNALPIP href "../config/installation/#externally-managed" + click PROJEMBEDDED href "../config/project/#embedding" + click DEPFILE href "../config/project/#dependency-file" + click SINGLEPROJECT href "../config/project/#identifier" + click DEPFILEINSTALL href "../config/project/#dependency-file" + click PROJEMBED href "../config/project/#embedding" + click MNG href "../config/cli/#management-command" + click MNGCMD href "../config/cli/#management-command" click MANAGE href "#commands" - click EXECUTE href "../config/#execution-mode" + click EXECUTE href "../config/project/#execution-mode" ``` ## Execution -Projects are [executed](config.md#execution-mode) using [`execvp`](https://linux.die.net/man/3/execvp) on non-Windows systems, replacing the process. +Projects are [executed](config/project.md#execution-mode) using [`execvp`](https://linux.die.net/man/3/execvp) on non-Windows systems, replacing the process. To provide consistent behavior on each user's machine: - Python runs projects in [isolated mode](https://docs.python.org/3/using/cmdline.html#cmdoption-I) -- When installing or upgrading projects, [pip](https://github.com/pypa/pip) uses [isolation](https://pip.pypa.io/en/stable/cli/pip/#cmdoption-isolated) ([by default](config.md#allowing-configuration)) +- When installing or upgrading projects, [pip](https://github.com/pypa/pip) uses [isolation](https://pip.pypa.io/en/stable/cli/pip/#cmdoption-isolated) ([by default](config/installation.md#allowing-configuration)) ## Detection -A single environment variable called `PYAPP` is injected with the value of `1` ([by default](config.md#installation-indicator)) when running applications and may be used to detect this mode of installation versus others. - -## Location - -The default location of your application's installation differs based on the operating system and can be overridden at runtime with the `PYAPP_INSTALL_DIR_` environment variable where `` is the uppercased version of the [project name](config.md#project). +A single environment variable called `PYAPP` is injected with the value of `1` ([by default](config/cli.md#installation-indicator)) when running applications and may be used to detect this mode of installation versus others. ## Commands -Built applications have a single top-level command group named `self` ([by default](config.md#management-command)) and all other invocations will be forwarded to your actual [execution logic](config.md#execution-mode). +Built applications have a single top-level command group named `self` ([by default](config/cli.md#management-command)) and all other invocations will be forwarded to your actual [execution logic](config/project.md#execution-mode). ### Default @@ -118,7 +114,7 @@ These commands are hidden by default and each can be individually exposed by set self metadata ``` -This displays [customized](config.md#metadata-template) output based on a template. +This displays [customized](config/cli.md#metadata-template) output based on a template. #### pip diff --git a/hatch.toml b/hatch.toml index a6e2fed..916a575 100644 --- a/hatch.toml +++ b/hatch.toml @@ -2,14 +2,15 @@ detached = true dependencies = [ "mkdocs~=1.5.3", - "mkdocs-material~=9.5.1", + "mkdocs-material~=9.5.18", # Plugins - "mkdocs-minify-plugin~=0.7.1", - "mkdocs-git-revision-date-localized-plugin~=1.2.1", - "mkdocs-glightbox~=0.3.5", + "mkdocs-minify-plugin~=0.8.0", + "mkdocs-git-revision-date-localized-plugin~=1.2.4", + "mkdocs-glightbox~=0.3.7", + "mkdocs-redirects~=1.2.1", "mike~=2.0.0", # Extensions - "pymdown-extensions~=10.5.0", + "pymdown-extensions~=10.8.0", # Necessary for syntax highlighting in code blocks "pygments~=2.17.2", # Validation diff --git a/mkdocs.yml b/mkdocs.yml index 6cc5380..ace75ed 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -47,9 +47,13 @@ nav: - About: index.md - How-to: how-to.md - Building: build.md - - Configuration: config.md - Runtime behavior: runtime.md - Examples: examples.md + - Configuration: + - Project: config/project.md + - Python distribution: config/distribution.md + - Installation: config/installation.md + - CLI: config/cli.md - Meta: - Users: users.md - Changelog: changelog.md @@ -64,6 +68,9 @@ plugins: git-revision-date-localized: strict: false type: date + redirects: + redirect_maps: + config.md: config/project.md # social: # enabled: !ENV [MKDOCS_IMAGE_PROCESSING, false]