workflow_shared docs build pr

_shared-docs-build-pr.yml

Ansible collection docs build (PR)

Jobs

ID	Name	Permissions
build-ansible-docs	Build Ansible Docs	contents: read

---

Inputs

Name (✅required)	Type	Default	Description
collection-name	string	${{ github.event.repository.name }}	The collection name in the form namespace.collection.
collection-path	string		This is the relative path component of the collection in question, for example community/general.
python	string	3.13	The version of Python to install.
ansible-ref	string	stable-2.18	The ref from which to install ansible, for example "stable-2.14" or "milestone".
init-dest-dir	string		A directory relative to the checkout where the init process has already been run.
init-lenient	boolean	False	Use the lenient option during build init. Has no effect if init-dest-dir is supplied. This is only passed to the HEAD build. The BASE build always runs with true.
init-fail-on-error	boolean	False	Use the fail-on-error option during build init. Has no effect if init-dest-dir is supplied. This is only passed to the HEAD build. The BASE build always runs with false.
init-antsibull-docs-version	string		The version of antsibull-docs to use during build init. Has no effect if init-dest-dir is supplied. If not supplied, the latest version from PyPI is used. If supplied, must be a git ref from the antsibull-docs repository.
init-antsibull-docs-repository	string	ansible-community/antsibull-docs	When init-antsibull-docs-version is specified, this is the GitHub repository to which init-antsibull-docs-version refers. Has no effect if init-dest-dir is supplied, or if init-antsibull-docs-version is not supplied.
init-index-rst-source	string		Copy the provided file to rst/index.rst intead of templating a default one.
init-project	string		Sets the project value in the Sphinx configuration.
init-copyright	string		Sets the copyright value in the Sphinx configuration.
init-title	string		Sets the title and html_short_title values in the Sphinx configuration. If init-html-short-title is also specified, only title will be set to the value specified here.
init-html-short-title	string		Sets the html_short_title value in the Sphinx configuration. If not specified, the value of init-title will be used.
init-extra-conf	string		A newline separated list of key=value entries that will be added to the generated conf.py.
init-extra-html-context	string		A newline separated list of key=value entries that will be added to the generated conf.py in html_context
init-extra-html-theme-options	string		A newline separated list of key=value entries that will be added to the generated conf.py in html_theme_options
init-append-conf-py	string		If provided, this text will be appended to the generated conf.py as-is.
artifact-name	string	${{ github.event.repository.name }}docs${{ github.event.pull_request.head.sha }}	The name of the artifact to upload.
diff-size-limit	number	60000	The max size of the diff, past which it will be truncated.
sort-files	boolean	True	If true, sort the trimmed and rendered list of files.
render-file-line	string	> * `$` $<path_tail>	A template used to render each line of the file list as markdown. This will be processed as a JavaScript regex replace string, and the following named capture groups can be referenced: - $ -- the single character "status" letter in the file list, like "A" or an added file or "M" for a modified file. - $<path_stub> -- the part of the path that will be discarded in the "trimmed" file list. - $<path_tail> -- the relative part of the path; this can be used to concatenate to a URL to create links to the published site. Note that literal $ characters must be escaped as $$ and literal backslashes must be escaped as \
render-diff-truncate-text	string	The diff output was truncated because it exceeded the maximum size.	Markdown text to be used if the diff text was truncated. It will be available in the render-diff template.
render-diff	string	✳ see action.yml for full default value	A template used to render the diff output as markdown. It will be interpreted as a pseudo-JavaScript template literal and the following variables are available for ${var} interpolation: - ${diff} -- the diff text - ${truncated_msg} -- empty if the diff is not truncated, otherwise the value of render-diff-truncate-text
extra-collections	string		A space separated list of additional collections to install prior to building the documentation.
provide-link-targets	string		A newline separated list of link targets that should not cause reference errors. A small RST file will be created during the build which contains these labels.
intersphinx-links	string		A newline separated list of entries to add to the intersphinx_mapping in the generated conf.py. Use the syntax identifier:https://server/path to add the identifier identifier with URL https://server/path.
squash-hierarchy	boolean	False	If 'true', the collection documentation will be created at top-level and not in a subdirectory namespace/collection_name/. Has no effect if init-dest-dir is supplied.

---

Secrets

Name (✅required)	Description

---

Outputs

Name	Description
artifact-name	The same artifact name as passed in, available as an output.
artifact-url	The URL to the build artifacts.
changed	If false, the PR does not change the documentation.
diff	The diff between the base and head of the PR.
diff-truncated	If true, the diff was truncated because it exceeded the max size.
diff-rendered	The markdownr rendered diff between the base and head of the PR.
diff-files	The raw file list from the diff output.
diff-files-trimmed	The file list from the diff with the paths trimmed.
diff-files-rendered	The markdown rendered file list from the diff.