Merge pull request #427 from dhellmann/hook-docs-details

move hook details to hook reference guide

Author: mergify[bot]

docs/customization.md

@@ -53,7 +53,7 @@ package name with the suffix `.yaml`, e.g. `torch.yaml` or
 ### Example config
 
 ```shell
-$ fromager --settings-dir=overrides/settings ...
+fromager --settings-dir=overrides/settings ...
 ```
 
 ```yaml
@@ -110,7 +110,7 @@ If the `pre_built` field is set for a variant, then fromager pulls and resolves
 wheels specified in the field from local wheels server spun up by fromager
 followed by upstream package servers instead of rebuilding the package from source.
 If an alternate package index is provided in the settings then that is the only
-index used.  
+index used.
 
 When downloading a prebuilt wheel by hand, make sure that the wheel is
 placed in the `<path to wheels-repo directory>/prebuilt` directory so that it is
@@ -229,296 +229,7 @@ requires = ["setuptools>=68.0.0", "torch", "triton"]
 
 ## Override plugins
 
-For more complex customization requirements, create an override plugin.
-
-Plugins are registered using [entry
-points](https://packaging.python.org/en/latest/specifications/entry-points/)
-so they can be discovered and loaded at runtime. In `pyproject.toml`,
-configure the entry point in the
-`project.entry-points."fromager.project_overrides"` namespace to
-link the [canonical distribution name](#canonical-distribution-names)
-to an importable module.
-
-```toml
-[project.entry-points."fromager.project_overrides"]
-flit_core = "package_plugins.flit_core"
-pyarrow = "package_plugins.pyarrow"
-torch = "package_plugins.torch"
-triton = "package_plugins.triton"
-```
-
-The plugins are treated as providing overriding implementations of
-functions with default implementations, so it is only necessary to
-implement the functions needed to make it possible to build the
-package.
-
-### download_source
-
-The `download_source()` function is responsible for downloading the
-source from a URL.
-
-The arguments are the `WorkContext`, the `Requirement` being
-evaluated, version of the package being downloaded, the URL
-from which the source can be downloaded as returned by `resolve_source`,
-and the output directory in which the source should be downloaded.  
-
-The return value should be a `pathlib.Path` file path to the downloaded source.
-
-```python
-def download_source(ctx, req, version, download_url):
-    ...
-    return path_to_source
-```  
-
-### resolve_source
-
-The `resolve_source()` function is responsible for resolving a
-requirement and acquiring the source for that version of a
-package. The default is to use pypi.org to resolve the requirement.  
-
-The arguments are the `WorkContext`, the `Requirement` being
-evaluated, and the URL to the sdist index.
-
-The return value is `Tuple[str, Version]` where the first member is
-the url from which the source can be downloaded and the second member
-is the version of the resolved package.
-
-```python
-def resolve_source(ctx, req, sdist_server_url):
-    ...
-    return (url, version)
-```
-
-### get_resolver_provider
-
-(pypi.org)=
-The `get_resolver_provider()` function allows an override to change
-the way requirement specifications are converted to fixed
-versions. The default implementation looks for published versions on a
-Python package index. Most overrides do not need to implement this
-hook unless they are building versions of packages not released to
-[https://pypi.org](pypi.org).
-
-For examples, refer to `fromager.resolver.PyPIProvider` and
-`fromager.resolver.GitHubTagProvider`.
-
-The arguments are the `WorkContext`, the `Requirement` being
-evaluated, a boolean indicating whether source distributions should be
-included, a boolean indicating whether built wheels should be
-included, and the URL for the sdist server.
-
-The return value must be an instance of a class that implements the
-`resolvelib.providers.AbstractProvider` API.
-
-The expectation is that it acts as an engine for any sort of package resolution
-whether it is for wheels or sources. The provider can
-therefore use any value as the "URL" that will help it decide what to
-download. For example, the `GitHubTagProvider` returns the actual tag
-name in case that is different from the version number encoded within
-that tag name.
-
-```python
-def get_resolver_provider(ctx, req, include_sdists, include_wheels, sdist_server_url):
-    ...
-```
-
-The `GenericProvider` is a convenient base class, or can be instantiated
-directly if given a `version_source` callable that returns an iterator of
-version values as `str` or `Version` objects.
-
-```python
-from fromager import resolver
-
-VERSION_MAP = {'1.0': 'first-release', '2.0': 'second-release'}
-
-def _version_source(
-        identifier: str,
-        requirements: resolver.RequirementsMap,
-        incompatibilities: resolver.CandidatesMap,
-    ) -> typing.Iterable[Version]:
-    return VERSION_MAP.keys()
-
-
-def get_resolver_provider(ctx, req, include_sdists, include_wheels, sdist_server_url):
-    return resolver.GenericProvider(version_source=_version_source, constraints=ctx.constraints)
-```
-
-### prepare_source
-
-The `prepare_source()` function is responsible for setting up a tree
-of source files in a format that is ready to be built. The default
-implementation unpacks the source archive and applies patches.
-
-The arguments are the `WorkContext`, the `Requirement` being
-evaluated, the `Path` to the source archive, and the version.
-
-The return value should be the `Path` to the root of the source tree,
-ideally inside the `ctx.work_dir` directory.
-
-```python
-def prepare_source(ctx, req, source_filename, version):
-    ...
-    return output_dir_name
-```
-
-### expected_source_archive_name
-
-The `expected_source_archive_name()` function is used to re-discover a
-source archive downloaded by a previous step, especially if the
-filename does not match the standard naming scheme for an sdist.
-
-The arguments are the `Requirement` being evaluated and the version to
-look for.
-
-The return value should be a string with the base filename (no paths)
-for the archive.
-
-```python
-def expected_source_archive_name(req, dist_version):
-    return f'apache-arrow-{dist_version}.tar.gz'
-```
-
-### expected_source_directory_name
-
-The `expected_source_directory_name()` function is used to re-discover
-the location of a source tree prepared by a previous step, especially
-if the name does not match the standard naming scheme for an sdist.
-
-The arguments are the `Requirement` being evaluated and the version to
-look for.
-
-The return value should be a string with the name of the source root
-directory relative to the `ctx.work_dir` where it was prepared.
-
-```python
-def expected_source_directory_name(req, dist_version):
-    return f'apache-arrow-{dist_version}/arrow-apache-arrow-{dist_version}'
-```
-
-### get_build_system_dependencies
-
-The `get_build_system_dependencies()` function should return the PEP
-517 build dependencies for a package.
-
-The arguments are the `WorkContext`, the `Requirement` being
-evaluated, and the `Path` to the root of the source tree.
-
-The return value is an iterable of requirement specification strings
-for build system dependencies for the package. The caller is
-responsible for evaluating the requirements with the current build
-environment settings to determine if they are actually needed.
-
-```python
-# pyarrow.py
-def get_build_system_dependencies(ctx, req, sdist_root_dir):
-    # The _actual_ directory with our requirements is different than
-    # the source root directory detected for the build because the
-    # source tree doesn't just include the python package.
-    return dependencies.default_get_build_system_dependencies(
-        ctx, req,
-        sdist_root_dir / 'python',
-    )
-```
-
-### get_build_backend_dependencies
-
-The `get_build_backend_dependencies()` function should return the PEP
-517 build dependencies for a package.
-
-The arguments are the `WorkContext`, the `Requirement` being
-evaluated, and the `Path` to the root of the source tree.
-
-The return value is an iterable of requirement specification strings
-for build backend dependencies for the package. The caller is
-responsible for evaluating the requirements with the current build
-environment settings to determine if they are actually needed.
-
-```python
-# pyarrow.py
-def get_build_backend_dependencies(ctx, req, sdist_root_dir):
-    # The _actual_ directory with our requirements is different than
-    # the source root directory detected for the build because the
-    # source tree doesn't just include the python package.
-    return dependencies.default_get_build_backend_dependencies(
-        ctx, req,
-        sdist_root_dir / 'python',
-    )
-```
-
-### get_build_sdist_dependencies
-
-The `get_build_sdist_dependencies()` function should return the PEP 517
-dependencies for building the source distribution for a package.
-
-The return value is an iterable of requirement specification strings
-for build backend dependencies for the package. The caller is
-responsible for evaluating the requirements with the current build
-environment settings to determine if they are actually needed.
-
-```python
-# pyarrow.py
-def get_build_sdist_dependencies(ctx, req, sdist_root_dir):
-    # The _actual_ directory with our requirements is different than
-    # the source root directory detected for the build because the
-    # source tree doesn't just include the python package.
-    return dependencies.default_get_build_sdist_dependencies(
-        ctx, req,
-        sdist_root_dir / 'python',
-    )
-```
-
-### build_sdist
-
-The `build_sdist()` function is responsible for creating a new source
-distribution from the prepared source tree and placing it in `ctx.sdists_build`.
-
-The arguments are the `WorkContext`, the `Requirement` being evaluated, and the
-`Path` to the root of the source tree.
-
-The return value is the `Path` to the newly created source distribution.
-
-```python
-# pyarrow.py
-def build_sdist(ctx, req, sdist_root_dir):
-    return sources.build_sdist(
-        ctx, req,
-        sdist_root_dir / 'python',
-    )
-```
-
-### build_wheel
-
-The `build_wheel()` function is responsible for creating a wheel from
-the prepared source tree and placing it in `ctx.wheels_build`.. The
-default implementation invokes `pip wheel` in a temporary directory
-and passes the path to the source tree as argument.
-
-The arguments are the `WorkContext`, the `Path` to a virtualenv
-prepared with the build dependencies, a `dict` with extra environment
-variables to pass to the build, the `Requirement` being evaluated, and
-the `Path` to the root of the source tree.
-
-The return value is ignored.
-
-```python
-def build_wheel(ctx, build_env, extra_environ, req, sdist_root_dir):
-    ...
-```  
-
-### add_extra_metadata_to_wheels  
-
-The `add_extra_metadata_to_wheels()` function is responsible to return any
-data the user would like to include in the wheels that fromager builds. This
-data will be added to the `fromager-build-settings` file under the `.dist-info`
-directory of the wheels. This file already contains the settings used to build
-that package.  
-
-The arguments available are `WorkContext`, `Requirement` being evaluated, the resolved
-`Version` of that requirement, a `dict` with extra environment variables, a `Path` to
-the root directory of the source distribution and a `Path` to the `.dist-info` directory
-of the wheel.  
-
-The return value must be a `dict`, otherwise it will be ignored.
+Override plugins are documented in [the reference guide](hooks.rst).
 
 ## Canonical distribution names