httk.core.docs.gitsite

Create the single orphan commit used by a generated documentation site.

Exceptions

GitSiteError

Raised when a generated site cannot be committed to a Git repository.

GitUnavailableError

Raised when the git executable is not available.

Classes

CommitSiteResult

Summarize a site commit operation.

Functions

commit_site(site_directory, branch, message, *[, ...])

Replace branch with one parentless commit containing site_directory.

Module Contents

exception httk.core.docs.gitsite.GitSiteError[source]

Bases: RuntimeError

Raised when a generated site cannot be committed to a Git repository.

exception httk.core.docs.gitsite.GitUnavailableError[source]

Bases: GitSiteError

Raised when the git executable is not available.

class httk.core.docs.gitsite.CommitSiteResult[source]

Summarize a site commit operation.

Parameters:

  • repository – Repository receiving the generated objects.

  • branch – Branch replaced by the new commit.

  • commit – Identifier of the parentless commit.

  • tree – Identifier of the committed site tree.

repository: pathlib.Path[source]
branch: str[source]
commit: str[source]
tree: str[source]
httk.core.docs.gitsite.commit_site(site_directory, branch, message, *, repository=None, author_name=None, author_email=None, committer_name=None, committer_email=None)[source]

Replace branch with one parentless commit containing site_directory.

The site is converted directly into Git objects, so the caller’s index and checked-out files are not changed. Ref leases for concurrent publishers remain the caller’s responsibility when pushing the resulting branch. Git dates remain ambient, so commit IDs are intentionally not deterministic.

Parameters:

  • site_directory (str | pathlib.Path) – Generated site tree to commit.

  • branch (str) – Branch to replace with the generated commit.

  • message (str) – Commit message for the generated commit.

  • repository (str | pathlib.Path | None) – Repository to update, or the site/current repository.

  • author_name (str | None) – Git author name, using the docs-bot default when omitted.

  • author_email (str | None) – Git author email, using the docs-bot default when omitted.

  • committer_name (str | None) – Git committer name, using the docs-bot default when omitted.

  • committer_email (str | None) – Git committer email, using the docs-bot default when omitted.

Returns:

Identifiers and paths for the generated commit.

Raises:
Return type:

CommitSiteResult