Repository Discovery

Module: thornforge.buildsite.repository

Overview

Repository discovery resolves the Sphinx source directory, project display name, project metadata pages, hash inputs, fallback version label, and Git capability for a source repository.

Important API

RepositoryProfile

Dataclass describing all discovered build inputs.

discover_repository_profile(repo_root)

Return the complete repository profile.

discover_docs_dir(repo_root)

Locate the most likely Sphinx source directory.

materialize_source(source)

Context manager that yields a local repository path for local or remote sources.

Autodoc

class thornforge.buildsite.repository.RepositoryProfile(repo_root: Path, docs_dir: Path, project_name: str, input_paths: tuple[str, ...], project_pages: tuple[tuple[Path, Path], ...], default_version_name: str, is_git_repo: bool)

Resolved repository metadata needed to drive a ThornForge build.

repo_root

Absolute repository root used for all subsequent file lookups.

Type:

pathlib.Path

docs_dir

Directory containing the Sphinx conf.py and source docs.

Type:

pathlib.Path

project_name

Best-effort display name used in generated pages.

Type:

str

input_paths

Repository-relative paths that should participate in build hashing so equivalent inputs can share the same output.

Type:

tuple[str, …]

project_pages

Mapping of source files to root-level published HTML outputs.

Type:

tuple[tuple[pathlib.Path, pathlib.Path], …]

default_version_name

Version label used when the repository does not provide matching release tags.

Type:

str

is_git_repo

Whether repo_root is backed by a readable Git checkout.

Type:

bool

default_version_name: str

docs_dir: Path

input_paths: tuple[str, ...]

is_git_repo: bool

project_name: str

project_pages: tuple[tuple[Path, Path], ...]

repo_root: Path

thornforge.buildsite.repository.discover_default_version_name(repo_root: Path, git_repo: bool) → str

Choose a fallback version label for repositories without release tags.

Parameters:

• repo_root – Repository root used to inspect metadata or Git state.

• git_repo – Whether repo_root supports Git commands.

Returns:

A version string from pyproject.toml when present, otherwise a git describe result for Git repositories, otherwise "current".

thornforge.buildsite.repository.discover_docs_dir(repo_root: Path) → Path

Find the most likely Sphinx documentation source directory.

Parameters:

repo_root – Repository root to inspect.

Returns:

The directory that most likely contains the project’s Sphinx sources. Common layouts such as docs/ and docs/source/ are preferred before falling back to a broader conf.py search.

Raises:

FileNotFoundError – If no plausible Sphinx source directory can be found.

thornforge.buildsite.repository.discover_input_paths(repo_root: Path, docs_dir: Path, project_pages: tuple[tuple[Path, Path], ...]) → tuple[str, ...]

Build the repository-relative paths that should participate in hashing.

Parameters:

• repo_root – Repository root used to test whether candidate files exist.

• docs_dir – Resolved documentation source directory.

• project_pages – Published project page mappings whose source files should also influence the build hash.

Returns:

Sorted repository-relative paths whose contents should influence the canonical build digest.

thornforge.buildsite.repository.discover_project_name(repo_root: Path) → str

Infer a display name for the target project.

Parameters:

repo_root – Repository root whose metadata files should be inspected.

Returns:

Project name from pyproject.toml or package.json when available; otherwise the repository directory name.

thornforge.buildsite.repository.discover_project_site_pages(repo_root: Path) → tuple[tuple[Path, Path], ...]

Map known metadata files to generated site pages.

Parameters:

repo_root – Repository root whose top-level files should be inspected.

Returns:

A tuple of (source_path, output_path) pairs describing which metadata files, such as README or CHANGELOG files, should be published as root-level HTML pages.

thornforge.buildsite.repository.discover_repository_profile(repo_root: Path) → RepositoryProfile

Discover the build-relevant structure of a target repository.

Parameters:

repo_root – Repository root to inspect.

Returns:

A RepositoryProfile containing resolved docs paths, metadata files, output page mappings, version defaults, and Git capability flags.

thornforge.buildsite.repository.is_remote_source(source: str) → bool

Return whether an input string looks like a supported GitHub remote.

Parameters:

source – Raw source string supplied by the user or CLI.

Returns:

True when the input resembles an HTTPS, SSH, or git@ GitHub repository URL that ThornForge knows how to clone.

thornforge.buildsite.repository.materialize_source(source: str | Path)

Yield a local repository path for either a local or remote source.

Parameters:

source – Local path or GitHub URL describing the repository to build.

Yields:

A resolved local Path pointing at a repository tree that can be inspected and built.

Side Effects:

May create and later delete a temporary directory when source refers to a remote GitHub repository.

Raises:

FileNotFoundError – If source is neither an existing local path nor a supported GitHub remote URL.