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(release_args='')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 |
|---|---|---|---|
| release_args | str | Additional arguments to pass to the gh release GitHub CLI command (default is ““). |
'' |
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()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.
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()