exasol_sphinx_github_pages_generator.generate_index module

exasol_sphinx_github_pages_generator.generate_index.change_and_restore(directory: pathlib.Path)

exasol_sphinx_github_pages_generator.generate_index.copy_importlib_resources_dir_tree(src_path: importlib_resources.abc.Traversable, target_path: pathlib.Path) → None

Uses a given source path “scr_path” given as an importlib_resources.abc.Traversable to copy all files/directories in the directory tree whose root is scr_path into target_path.

Parameters

• src_path – Root of the dir tree to be copied, given as importlib_resources.abc.Traversable.

• target_path – Path object the dir tree should be copied to.

exasol_sphinx_github_pages_generator.generate_index.copy_importlib_resources_file(src_file: importlib_resources.abc.Traversable, target_file: pathlib.Path) → None

Uses a given source path “src_file” given as an importlib_resources.abc.Traversable to copy the file it points to into the destination denoted by target_path.

Parameters

• src_file – Location of the file to be copied, given as importlib_resources.abc.Traversable.

• target_file – Path object the location file should be copied to.

exasol_sphinx_github_pages_generator.generate_index.find_index(target_worktree: pathlib.Path, source_branch: str) → pathlib.Path

For the given source_branch find the index.html file in its documentation files, and return its path. Aborts if there are more or less than exactly one (1) index.html file.

Parameters

• target_worktree – Worktree/path all generated project documentation is put into.

• source_branch – Name of the branch the documentation should be searched for.

Returns

Path pointing at found index.html file

exasol_sphinx_github_pages_generator.generate_index.generate_release_dicts(release_list: Union[Generator[str, None, Any], List[str]], source_branch: str, target_worktree: pathlib.Path) → List[Dict[str, str]]

Given a list of releases, generate a list of dictionaries containing the name of the release, and the path to its documentation relative to target_worktree. The current release is titled “latest”.

Parameters

• release_list – List or Generator of release-names as strings.

• source_branch – The branch we are currently generating the documentation for.

• target_worktree – Worktree/path all generated project documentation is put into.

Returns

List of dictionaries containing the release name and path to its index.html file.

exasol_sphinx_github_pages_generator.generate_index.generate_release_index(target_branch: str, target_worktree: pathlib.Path, source_branch: str, target_branch_exists_remote: bool) → None

Generates a release index file from a given target_branch into the target_worktree. Uses the “furo” theme for the generated release index file. Source_branch will be called “latest” in the resulting release index. Also adds the template file to “_sources”. Aborts if not currently in given source_branch.

Parameters

• target_branch – The branch the generated documentation should end up on.

• target_worktree – Worktree/path all generated project documentation is put into.

• source_branch – The branch we are currently generating the documentation for.

• target_branch_exists_remote – Bool representing whether the target_branch already exist in the remote repository.

exasol_sphinx_github_pages_generator.generate_index.get_releases(target_branch: str, target_branch_exists_remote: bool, source_branch: str, target_worktree: pathlib.Path) → List[Dict[str, str]]

Find all releases already documented in target_branch, and return them with the path pointing to their index.html file. Additionally, also return the current release and index.html-file-path. The current release is titled “latest”. Found releases are returned as a list of dictionaries. In order to find the releases in the target_branch, it is checked out in an additional temporary worktree. Takes the root-directory name for each release and returns it. Gives bad results if branch names contain slashes, because these result in nested directories instead of one directory, therefore only the first part of the branch name is found by this function. Please remove slashes from branch names before using them to generate the root directory for your release-documentation.

Parameters

• target_branch – The branch the generated documentation should end up on.

• target_branch_exists_remote – Bool representing whether the target_branch already exist in the remote repository.

• source_branch – The branch we are currently generating the documentation for.

• target_worktree – Worktree/path all generated project documentation is put into.

Returns

List of dictionaries containing the release name and path to its index.html file.