exasol_sphinx_github_pages_generator.deployer module#

class exasol_sphinx_github_pages_generator.deployer.GithubPagesDeployer(source_dir: str, source_branch: str, source_origin: str, current_commit_id: str, module_path: list, target_branch: str, push_origin: str, push_enabled: str, tempdir: str)#

Bases: object

Builds and deploys GitHub Pages using Sphinx given a branch.

Parameters

  • source_dir – Path to the directory inside the source_branch where the index.rst and conf.py reside in.

  • source_branch – The branch-name or tag the documentation files should be generated for. Will use remote branch for generation. Local unpushed changes will cause program exit or be ignored.

  • current_commit_id – CommitID of the current branch.

  • module_path – List of modules/packages in the source_branch that should be documented.

  • target_branch – Branch the documentation should be generated into.

  • push_origin – origin of the Git Repository.

  • source_origin – origin of the source branch. “origin” results in “refs/remotes/origin/source_branch”, other results in “refs/source_origin/source_branch”. Example: source_origin = tags, source_branch = tag_name result : “refs/tags/tag_name”

  • push_enabled – Set to “push” if generated files should be pushed to the remote, otherwise set to “commit”.

  • tempdir – Path of the temporary directory this Generator runs in.

build_and_copy_documentation() → pathlib.Path#

Build the html documentation files using “sphinx-apidoc” and “sphinx-build”, then copies them into the target branch. If an older version of the files exist for the source branch, on the target_branch, these are deleted first.

:returns the path of the generated files inside the target_branch worktree.

check_out_source_branch_as_worktree(source_branch_exists_locally: int) → None#

Creates a separate Git worktree for the source_branch if the existing worktree has a different branch currently checked out. This way, the local current Git Repository is kept in its original state. The new worktree is created at self.worktree_paths[“source_worktree”]. !! Uses remote branch for generating the documentation, all stashed or unpushed changes will be ignored !! Exits with error if source_branch does not exist in the remote repository.

Parameters

source_branch_exists_locally – Indicates if the source_branch exists in the local repository. If 0, it exists, else it does not

checkout_target_branch_as_worktree() → None#

Creates a separate worktree for the target branch and checks it out. If the target_branch already exists in remote, it is checked out into a new local worktree. Else, target_branch is added as a new branch with a separate worktree and set as default for GitHub Pages.

clean_worktree(original_workdir: str) → None#

Deletes the temporary worktrees and resets the working directory to the given working directory in order to ensure it points to an existing directory.

Parameters

original_workdir – A directory that can be used as the working directory after the generator finishes. Preferably the original working-directory.

detect_or_verify_source_branch() → None#

Tries to find a valid source_branch. If source_branch is set, checks if it is equal to the current branch. If not, switches branches. Tries to use the current branch if source_branch is not set. Exits if this fails. Also fails if the detected source branch has local uncommitted/pushed changes or is not up-to-date with the remote.

git_commit_and_push(output_dir: pathlib.Path) → None#

Commits and pushes the generated documentation files to the remote GitHUb repository. Also adds a file describing the source branch and commit of the generated files, and generates a release index file using functions in generate_index.py. Does nothing if no changes occurred.

Parameters

output_dir – Path of the generated files inside the target_branch worktree.