docs

docs

Module for managing documentation versions.

Determine the appropriate version and alias for the documentation website based on the latest release tag and the current hash.

Functions

Name	Description
action_markdown_desc	Generates a markdown formatted description for a given action.
action_markdown_header	Generates a markdown header for a given action.
action_markdown_io	Generates a markdown string documenting the inputs and outputs of a given action.
get_docs_version	Get correct version and alias for documentation website.
parse_action_yaml	Parses a YAML file and returns its contents as a dictionary.
set_docs_version	Set version and alias in GitHub environment variables for docs website action.

action_markdown_desc

docs.action_markdown_desc(action_dict)

Generates a markdown formatted description for a given action.

Parameters

Name	Type	Description	Default
action_dict	dict	A dictionary containing action details. Expected keys are: - “name” (str): The name of the action. - “description” (str): A brief description of the action.	required

Returns

Name	Type	Description
str		A markdown formatted string with the action name in bold and code format, followed by the description.

action_markdown_header

docs.action_markdown_header(action_dict)

Generates a markdown header for a given action.

Parameters

Name	Type	Description	Default
action_dict	dict	A dictionary containing action details. Expected keys are: - “name” (str): The name of the action. - “description” (str): A brief description of the action.	required

Returns

Name	Type	Description
str		A formatted markdown string with the action’s name as a header and the description as the content.

action_markdown_io

docs.action_markdown_io(action_dict)

Generates a markdown string documenting the inputs and outputs of a given action.

Parameters

Name	Type	Description	Default
action_dict	dict	A dictionary containing the action’s inputs and outputs. The dictionary should have the following structure: { “inputs”: { “input_name”: { “description”: “Description of the input”, “required”: bool, “default”: “default_value” }, … }, “outputs”: { “output_name”: { “description”: “Description of the output” }, … } }	required

Returns

Name	Type	Description
str		A markdown formatted string documenting the inputs and outputs of the action.

get_docs_version

docs.get_docs_version(
    repo,
    release_args='',
    release_tag=None,
    strict_semver=True,
)

Get correct version and alias for documentation website.

Determines the appropriate version and alias for the documentation based on the latest release tag and the current hash.

Parameters

Name	Type	Description	Default
repo	str	The name of the GitHub repository to check for releases.	required
release_args	str	Additional arguments to pass to the gh release GitHub CLI command (default is ““).	''
release_tag	str	The tag of the release (default: None). Set this when running this code from a github release event. Only set this if the tag is currently checked out.	None
strict_semver	bool	If True, the version string must match the full semantic versioning pattern. Otherwise, a relaxed format with only the major and minor components is allowed.	True

Returns

Name	Type	Description
tuple		A tuple containing: - docs_version (str): The major and minor version of the latest release. - docs_alias (str): The alias for the documentation version, e.g., “latest”.

Raises

Name	Type	Description
	ValueError	If the current commit hash is not a descendant of the latest release.

See Also

set_docs_version: Sets the version and alias in the GitHub environment.

Examples

>>> get_docs_version()
('1.0', 'latest')

parse_action_yaml

docs.parse_action_yaml(filename)

Parses a YAML file and returns its contents as a dictionary.

Parameters

Name	Type	Description	Default
filename	str	The path to the YAML file to be parsed.	required

Returns

Name	Type	Description
dict		The contents of the YAML file as a dictionary.

set_docs_version

docs.set_docs_version(
    repo,
    release_tag=None,
    strict_semver=True,
    environ='GITHUB_OUTPUT',
)

Set version and alias in GitHub environment variables for docs website action.

This function retrieves the documentation version and alias using get_docs_version and sets them as environment variables in the GitHub Actions environment.

Parameters

Name	Type	Description	Default
repo	str	The name of the GitHub repository to check for releases.	required
release_tag	str	Specific release tag to use for determining the version. Defaults to None.	None
strict_semver	bool	Whether to enforce strict semantic versioning. Defaults to True.	True

Raises

Name	Type	Description
	ValueError	If the current commit hash is not a descendant of the latest release.

See Also

get_docs_version: Retrieves the documentation version and alias. set_output: Sets the GitHub Actions environment variable.

Examples

>>> set_docs_version()