Add autodoc for hooks functions

Add a custom `autofromagerhook` ReST directive to document Fromager
hooks and their signatures. The intersphinx links are used to reference
documentation of stdlib, packaging, and pyproject hooks types.

Also renames `_check_archive_name_in_settings` and adds two dummy
default functions for documentation.

Signed-off-by: Christian Heimes <[email protected]>

Author: tiran

docs/conf.py

@@ -1,5 +1,11 @@
 from importlib import metadata
 
+from sphinx.addnodes import desc_signature
+from sphinx.application import Sphinx
+from sphinx.domains.python import PyFunction
+from sphinx.ext.autodoc import FunctionDocumenter
+from sphinx.util.typing import ExtensionMetadata
+
 # Configuration file for the Sphinx documentation builder.
 #
 # For the full list of built-in configuration values, see the documentation:
@@ -20,6 +26,8 @@
     "sphinx_click",
     "myst_parser",
     "sphinxcontrib.autodoc_pydantic",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
 ]
 
 # Recognized suffixes
@@ -33,6 +41,13 @@
 
 language = "English"
 
+# references to Python stdlib and packaging
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "packaging": ("https://packaging.pypa.io/en/stable/", None),
+    "pyproject-hooks": ("https://pyproject-hooks.readthedocs.io/en/latest/", None),
+}
+
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
@@ -46,3 +61,34 @@
 autodoc_pydantic_model_show_config_summary = False
 autodoc_pydantic_model_show_validator_summary = False
 autodoc_pydantic_model_show_validator_members = False
+
+# autodoc_typehints_format = "fully-qualified"
+
+
+class FromagerHookDocumenter(FunctionDocumenter):
+    """Documenter for 'autofromagehook' directive"""
+
+    objtype = "fromagerhook"
+
+    def format_name(self):
+        name = super().format_name()
+        if name.startswith("default_"):
+            name = name[8:]
+        return name
+
+
+class PyFromagerHook(PyFunction):
+    """:py:fromagehook"""
+
+    def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]:
+        # hack to remove module prefix from output
+        self.options["module"] = None
+        return super().handle_signature(sig, signode)
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    app.setup_extension("sphinx.ext.autodoc")
+    app.add_directive_to_domain("py", FromagerHookDocumenter.objtype, PyFromagerHook)
+    app.add_autodocumenter(FromagerHookDocumenter)
+
+    return {"version": release, "parallel_read_safe": True}

docs/hooks.rst

@@ -0,0 +1,66 @@
+Fromager hooks
+==============
+
+Dependency hooks
+----------------
+
+.. py:currentmodule:: fromager.dependencies
+
+.. autofromagerhook:: default_get_build_system_dependencies
+
+.. autofromagerhook:: default_get_build_backend_dependencies
+
+.. autofromagerhook:: default_get_build_sdist_dependencies
+
+
+Finder hooks
+------------
+
+.. py:currentmodule:: fromager.finders
+
+.. autofromagerhook:: default_expected_source_archive_name
+
+.. autofromagerhook:: default_expected_source_directory_name
+
+
+Resolver hooks
+--------------
+
+.. currentmodule:: fromager.resolver
+
+.. autofromagerhook:: default_resolver_provider
+
+
+Source hooks
+------------
+
+.. currentmodule:: fromager.sources
+
+.. autofromagerhook:: default_resolve_source
+
+.. autofromagerhook:: default_download_source
+
+.. autofromagerhook:: default_prepare_source
+
+.. autofromagerhook:: default_build_sdist
+
+
+Wheel hooks
+-----------
+
+.. currentmodule:: fromager.wheels
+
+.. autofromagerhook:: default_build_wheel
+
+.. autofromagerhook:: default_add_extra_metadata_to_wheels
+
+
+Additional types
+----------------
+
+.. autoclass:: fromager.build_environment.BuildEnvironment
+.. autoclass:: fromager.context.WorkContext
+.. autoclass:: fromager.resolver.PyPIProvider
+.. autoclass:: fromager.resolver.GenericProvider
+.. autoclass:: fromager.resolver.GitHubTagProvider
+.. autofunction:: fromager.sources.prepare_new_source

docs/index.rst

@@ -28,6 +28,7 @@ those special cases directly into fromager.
 
    using.md
    customization.md
+   hooks.rst
    config-reference.rst
    cli.rst
    develop.md

src/fromager/dependencies.py

@@ -70,6 +70,10 @@ def default_get_build_system_dependencies(
     sdist_root_dir: pathlib.Path,
     build_dir: pathlib.Path,
 ) -> typing.Iterable[str]:
+    """Get build system requirements
+
+    Defaults to ``pyproject.toml`` ``[build-system] requires``.
+    """
     pyproject_toml = get_pyproject_contents(build_dir)
     return typing.cast(list[str], get_build_backend(pyproject_toml)["requires"])
 
@@ -115,6 +119,11 @@ def default_get_build_backend_dependencies(
     sdist_root_dir: pathlib.Path,
     build_dir: pathlib.Path,
 ) -> typing.Iterable[str]:
+    """Get build backend dependencies
+
+    Defaults to result of hook call
+    :meth:`~pyproject_hooks.BuildBackendHookCaller.get_requires_for_build_wheel`
+    """
     pbi = ctx.package_build_info(req)
     pyproject_toml = get_pyproject_contents(build_dir)
     extra_environ = pbi.get_extra_environ()
@@ -165,6 +174,11 @@ def default_get_build_sdist_dependencies(
     sdist_root_dir: pathlib.Path,
     build_dir: pathlib.Path,
 ) -> typing.Iterable[str]:
+    """Get build sdist dependencies
+
+    Defaults to result of hook call
+    :meth:`~pyproject_hooks.BuildBackendHookCaller.get_requires_for_build_wheel`
+    """
     pbi = ctx.package_build_info(req)
     pyproject_toml = get_pyproject_contents(build_dir)
     extra_environ = pbi.get_extra_environ()

src/fromager/finders.py

@@ -21,7 +21,7 @@ def _dist_name_to_filename(dist_name: str) -> str:
     return re.sub(r"[^\w\d.]+", "_", canonical_name, flags=re.UNICODE)
 
 
-def _check_archive_name_in_settings(
+def default_expected_source_archive_name(
     ctx: context.WorkContext,
     req: Requirement,
     dist_version: str,
@@ -39,7 +39,7 @@ def find_sdist(
     sdist_file_name = overrides.find_and_invoke(
         req.name,
         "expected_source_archive_name",
-        _check_archive_name_in_settings,
+        default_expected_source_archive_name,
         req=req,
         dist_version=dist_version,
         ctx=ctx,
@@ -126,6 +126,10 @@ def find_wheel(
     return None
 
 
+def default_expected_source_directory_name(req: Requirement, dist_version: str) -> str:
+    raise NotImplementedError
+
+
 def find_source_dir(
     ctx: context.WorkContext,
     work_dir: pathlib.Path,
@@ -148,7 +152,7 @@ def find_source_dir(
     sdist_name = overrides.find_and_invoke(
         req.name,
         "expected_source_archive_name",
-        _check_archive_name_in_settings,
+        default_expected_source_archive_name,
         req=req,
         dist_version=dist_version,
         ctx=ctx,

src/fromager/resolver.py

@@ -67,7 +67,8 @@ def default_resolver_provider(
     sdist_server_url: str,
     include_sdists: bool,
     include_wheels: bool,
-) -> "PyPIProvider":
+) -> "PyPIProvider | GenericProvider | GitHubTagProvider":
+    """Lookup resolver provider to resolve package versions"""
     return PyPIProvider(
         include_sdists=include_sdists,
         include_wheels=include_wheels,
@@ -254,6 +255,8 @@ def find_matches(
 
 
 class PyPIProvider(BaseProvider):
+    """Lookup package and versions from a simple Python index (PyPI)"""
+
     def __init__(
         self,
         include_sdists: bool = True,
@@ -331,6 +334,8 @@ def find_matches(
 
 
 class GenericProvider(BaseProvider):
+    """Lookup package and version by using a callback"""
+
     def __init__(
         self,
         version_source: VersionSource,
@@ -401,6 +406,11 @@ def find_matches(
 
 
 class GitHubTagProvider(GenericProvider):
+    """Lookup package and versions from a GitHub repository tags
+
+    Supports :envvar:`GITHUB_TOKEN` for authentication.
+    """
+
     def __init__(
         self, organization: str, repo: str, constraints: Constraints | None = None
     ):

src/fromager/sources.py

@@ -381,6 +381,10 @@ def default_prepare_source(
     source_filename: pathlib.Path,
     version: Version,
 ) -> tuple[pathlib.Path, bool]:
+    """Unpack and modify sdist sources
+
+    Calls :func:`~fromager.sources.prepare_new_source` by default.
+    """
     source_root_dir, is_new = unpack_source(
         ctx=ctx,
         req=req,
@@ -405,7 +409,11 @@ def prepare_new_source(
 ) -> None:
     """Default steps for new sources
 
-    `default_prepare_source` runs this function when the sources are new.
+    - patch sources
+    - apply project overrides from settings
+    - vendor Rust dependencies
+
+    :func:`~default_prepare_source` runs this function when the sources are new.
     """
     patch_source(ctx, source_root_dir, req, version)
     pyproject.apply_project_override(
@@ -423,6 +431,7 @@ def build_sdist(
     sdist_root_dir: pathlib.Path,
     build_env: build_environment.BuildEnvironment,
 ) -> pathlib.Path:
+    """Build source distribution"""
     pbi = ctx.package_build_info(req)
     build_dir = pbi.build_dir(sdist_root_dir)
 

src/fromager/wheels.py

@@ -101,6 +101,17 @@ def _extra_metadata_elfdeps(
     return elfinfos
 
 
+def default_add_extra_metadata_to_wheels(
+    ctx: context.WorkContext,
+    req: Requirement,
+    version: Version,
+    extra_environ: dict[str, str],
+    sdist_root_dir: pathlib.Path,
+    dist_info_dir: pathlib.Path,
+) -> dict[str, typing.Any]:
+    raise NotImplementedError
+
+
 def add_extra_metadata_to_wheels(
     ctx: context.WorkContext,
     req: Requirement,

tox.ini

@@ -1,6 +1,6 @@
 [tox]
 minversion = 3.2.0
-envlist=py,linter,mypy,coverage-report
+envlist=py,linter,mypy,docs,coverage-report
 
 [testenv]
 extras = test
@@ -39,8 +39,8 @@ base_python=python3.11
 deps=
     ruff
 commands =
-    ruff format src tests
-    ruff check --fix src tests
+    ruff format src tests docs
+    ruff check --fix src tests docs
 skip_install = true
 skip_sdist = true