From 22e0c937d896d554d6b6b09a3da1c23faf614fe3 Mon Sep 17 00:00:00 2001 From: Sergey <6213510+sshnaidm@users.noreply.github.com> Date: Sat, 4 Nov 2023 13:31:27 +0200 Subject: [PATCH] Fix the docs for new modules (#667) Signed-off-by: Sagi Shnaidman --- docs/_static/sphinx_highlight.js | 144 +++++++++ docs/environment_variables.html | 185 ++++++++++++ docs/podman_container_exec_module.html | 362 ++++++++++++++++++++++ docs/podman_prune_module.html | 402 +++++++++++++++++++++++++ docs/podman_runlabel_module.html | 226 ++++++++++++++ 5 files changed, 1319 insertions(+) create mode 100644 docs/_static/sphinx_highlight.js create mode 100644 docs/environment_variables.html create mode 100644 docs/podman_container_exec_module.html create mode 100644 docs/podman_prune_module.html create mode 100644 docs/podman_runlabel_module.html diff --git a/docs/_static/sphinx_highlight.js b/docs/_static/sphinx_highlight.js new file mode 100644 index 00000000..aae669d7 --- /dev/null +++ b/docs/_static/sphinx_highlight.js @@ -0,0 +1,144 @@ +/* Highlighting utilities for Sphinx HTML documentation. */ +"use strict"; + +const SPHINX_HIGHLIGHT_ENABLED = true + +/** + * highlight a given string on a node by wrapping it in + * span elements with the given class name. + */ +const _highlight = (node, addItems, text, className) => { + if (node.nodeType === Node.TEXT_NODE) { + const val = node.nodeValue; + const parent = node.parentNode; + const pos = val.toLowerCase().indexOf(text); + if ( + pos >= 0 && + !parent.classList.contains(className) && + !parent.classList.contains("nohighlight") + ) { + let span; + + const closestNode = parent.closest("body, svg, foreignObject"); + const isInSVG = closestNode && closestNode.matches("svg"); + if (isInSVG) { + span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); + } else { + span = document.createElement("span"); + span.classList.add(className); + } + + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + parent.insertBefore( + span, + parent.insertBefore( + document.createTextNode(val.substr(pos + text.length)), + node.nextSibling + ) + ); + node.nodeValue = val.substr(0, pos); + + if (isInSVG) { + const rect = document.createElementNS( + "http://www.w3.org/2000/svg", + "rect" + ); + const bbox = parent.getBBox(); + rect.x.baseVal.value = bbox.x; + rect.y.baseVal.value = bbox.y; + rect.width.baseVal.value = bbox.width; + rect.height.baseVal.value = bbox.height; + rect.setAttribute("class", className); + addItems.push({ parent: parent, target: rect }); + } + } + } else if (node.matches && !node.matches("button, select, textarea")) { + node.childNodes.forEach((el) => _highlight(el, addItems, text, className)); + } +}; +const _highlightText = (thisNode, text, className) => { + let addItems = []; + _highlight(thisNode, addItems, text, className); + addItems.forEach((obj) => + obj.parent.insertAdjacentElement("beforebegin", obj.target) + ); +}; + +/** + * Small JavaScript module for the documentation. + */ +const SphinxHighlight = { + + /** + * highlight the search words provided in localstorage in the text + */ + highlightSearchWords: () => { + if (!SPHINX_HIGHLIGHT_ENABLED) return; // bail if no highlight + + // get and clear terms from localstorage + const url = new URL(window.location); + const highlight = + localStorage.getItem("sphinx_highlight_terms") + || url.searchParams.get("highlight") + || ""; + localStorage.removeItem("sphinx_highlight_terms") + url.searchParams.delete("highlight"); + window.history.replaceState({}, "", url); + + // get individual terms from highlight string + const terms = highlight.toLowerCase().split(/\s+/).filter(x => x); + if (terms.length === 0) return; // nothing to do + + // There should never be more than one element matching "div.body" + const divBody = document.querySelectorAll("div.body"); + const body = divBody.length ? divBody[0] : document.querySelector("body"); + window.setTimeout(() => { + terms.forEach((term) => _highlightText(body, term, "highlighted")); + }, 10); + + const searchBox = document.getElementById("searchbox"); + if (searchBox === null) return; + searchBox.appendChild( + document + .createRange() + .createContextualFragment( + '

' + + '' + + _("Hide Search Matches") + + "

" + ) + ); + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords: () => { + document + .querySelectorAll("#searchbox .highlight-link") + .forEach((el) => el.remove()); + document + .querySelectorAll("span.highlighted") + .forEach((el) => el.classList.remove("highlighted")); + localStorage.removeItem("sphinx_highlight_terms") + }, + + initEscapeListener: () => { + // only install a listener if it is really needed + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return; + if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) { + SphinxHighlight.hideSearchWords(); + event.preventDefault(); + } + }); + }, +}; + +_ready(SphinxHighlight.highlightSearchWords); +_ready(SphinxHighlight.initEscapeListener); diff --git a/docs/environment_variables.html b/docs/environment_variables.html new file mode 100644 index 00000000..69077887 --- /dev/null +++ b/docs/environment_variables.html @@ -0,0 +1,185 @@ + + + + + + + + + Index of all Collection Environment Variables — Python documentation + + + + + + + + + + + + + + + + + +
+
+
+ + +
+ +
+

Index of all Collection Environment Variables

+

The following index documents all environment variables declared by plugins in collections. +Environment variables used by the ansible-core configuration are documented in ansible_configuration_settings.

+
+
+ANSIBLE_BECOME_PASS
+

Password to pass to sudo

+

Used by: +containers.podman.podman_unshare become plugin

+
+ +
+
+ANSIBLE_PODMAN_EXECUTABLE
+

Executable for podman command.

+

Used by: +containers.podman.podman connection plugin

+
+ +
+
+ANSIBLE_PODMAN_EXTRA_ARGS
+

Extra arguments to pass to the podman command line.

+

Used by: +containers.podman.podman connection plugin

+
+ +
+
+ANSIBLE_SUDO_EXE
+

Sudo executable

+

Used by: +containers.podman.podman_unshare become plugin

+
+ +
+
+ANSIBLE_SUDO_PASS
+

Password to pass to sudo

+

Used by: +containers.podman.podman_unshare become plugin

+
+ +
+
+ANSIBLE_SUDO_USER
+

User you ‘become’ to execute the task (‘root’ is not a valid value here).

+

Used by: +containers.podman.podman_unshare become plugin

+
+ +
+ + +
+ +
+
+ +
+
+
+ ©. + + | + Powered by Sphinx 7.0.1 + & Alabaster 0.7.13 + + | + Page source +
+ + + + + + \ No newline at end of file diff --git a/docs/podman_container_exec_module.html b/docs/podman_container_exec_module.html new file mode 100644 index 00000000..fb5c6ca7 --- /dev/null +++ b/docs/podman_container_exec_module.html @@ -0,0 +1,362 @@ + + + + + + + + + containers.podman.podman_container_exec module – Executes a command in a running container. — Python documentation + + + + + + + + + + + + + + + + + + + +
+
+
+ + +
+ +
+

containers.podman.podman_container_exec module – Executes a command in a running container.

+
+

Note

+

This module is part of the containers.podman collection (version 1.11.0).

+

It is not included in ansible-core. +To check whether it is installed, run ansible-galaxy collection list.

+

To install it, use: ansible-galaxy collection install containers.podman. +You need further requirements to be able to use this module, +see Requirements for details.

+

To use it in a playbook, specify: containers.podman.podman_container_exec.

+
+ +
+

Synopsis

+
    +

  • Executes a command in a running container.

    • +
+
+
+

Requirements

+

The below requirements are needed on the host that executes this module.

+
    +

  • podman

    • +
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter

Comments

+

argv

+

list / elements=string

+

Passes the command as a list rather than a string.

+

One of the command or args is required.

+
+

command

+

string

+

The command to run in the container.

+

One of the command or args is required.

+
+

detach

+

boolean

+

If true, the command runs in the background.

+

The exec session is automatically removed when it completes.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+
+

env

+

dictionary

+

Set environment variables.

+
+

name

+

string / required

+

Name of the container where the command is executed.

+
+

privileged

+

boolean

+

Give extended privileges to the container.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+
+

tty

+

boolean

+

Allocate a pseudo-TTY.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+
+

user

+

string

+

The username or UID used and, optionally, the groupname or GID for the specified command.

+

Both user and group may be symbolic or numeric.

+
+

workdir

+

string

+

Working directory inside the container.

+
+
+
+

Notes

+
+

Note

+ +
+
+
+

Examples

+
- name: Execute a command with workdir
+  containers.podman.podman_container_exec:
+    name: ubi8
+    command: "cat redhat-release"
+    workdir: /etc
+
+- name: Execute a command with a list of args and environment variables
+  containers.podman.podman_container_exec:
+    name: test_container
+    argv:
+      - /bin/sh
+      - -c
+      - echo $HELLO $BYE
+    env:
+      HELLO: hello world
+      BYE: goodbye world
+
+- name: Execute command in background by using detach
+  containers.podman.podman_container_exec:
+    name: detach_container
+    command: "cat redhat-release"
+    detach: true
+
+
+
+
+

Return Values

+

Common return values are documented here, the following are the fields unique to this module:

+ + + + + + + + + + + + + + + + + + + + +

Key

Description

+

exec_id

+

string

+

The ID of the exec session.

+

Returned: success and detach=true

+

Sample: "f99002e34c1087fd1aa08d5027e455bf7c2d6b74f019069acf6462a96ddf2a47"

+
+

rc

+

integer

+

The exit code of the command executed in the container.

+

Returned: success

+

Sample: 0

+
+

stderr

+

string

+

The standard output of the command executed in the container.

+

Returned: success

+
+

stdout

+

string

+

The standard output of the command executed in the container.

+

Returned: success

+
+
+

Authors

+
    +

  • Takuya Nishimura (@nishipy)

    • +
+
+ +
+
+ + +
+ +
+
+ +
+
+
+ ©. + + | + Powered by Sphinx 7.0.1 + & Alabaster 0.7.13 + + | + Page source +
+ + + + + + \ No newline at end of file diff --git a/docs/podman_prune_module.html b/docs/podman_prune_module.html new file mode 100644 index 00000000..cce1d753 --- /dev/null +++ b/docs/podman_prune_module.html @@ -0,0 +1,402 @@ + + + + + + + + + containers.podman.podman_prune module – Allows to prune various podman objects — Python documentation + + + + + + + + + + + + + + + + + + + +
+
+
+ + +
+ +
+

containers.podman.podman_prune module – Allows to prune various podman objects

+
+

Note

+

This module is part of the containers.podman collection (version 1.11.0).

+

It is not included in ansible-core. +To check whether it is installed, run ansible-galaxy collection list.

+

To install it, use: ansible-galaxy collection install containers.podman. +You need further requirements to be able to use this module, +see Requirements for details.

+

To use it in a playbook, specify: containers.podman.podman_prune.

+
+

New in containers.podman 1.10.0

+ +
+

Synopsis

+
    +

  • Allows to run podman container prune, podman image prune, podman network prune, podman volume prune and podman system prune

    • +
+
+
+

Requirements

+

The below requirements are needed on the host that executes this module.

+
    +

  • Podman installed on host

    • +
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter

Comments

+

container

+

boolean

+

Whether to prune containers.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+
+

container_filters

+

dictionary

+

A dictionary of filter values used for selecting containers to delete.

+

For example, until: 24h.

+

See the podman documentation for more information on possible filters.

+
+

executable

+

string

+

Podman binary.

+

Default: "podman"

+
+

image

+

boolean

+

Whether to prune images.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+
+

image_filters

+

dictionary

+

A dictionary of filter values used for selecting images to delete.

+

You can also use dangling_only: false to delete dangling and non-dangling images or external: true to delete images even when they are used by external containers.

+

See the podman documentation for more information on possible filters.

+
+

network

+

boolean

+

Whether to prune networks.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+
+

network_filters

+

dictionary

+

A dictionary of filter values used for selecting networks to delete.

+

See the podman documentation for more information on possible filters.

+
+

system

+

boolean

+

Whether to prune unused pods, containers, image, networks and volume data

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+
+

system_all

+

boolean

+

Whether to prune all unused images, not only dangling images.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+
+

system_volumes

+

boolean

+

Whether to prune volumes currently unused by any container.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+
+

volume

+

boolean

+

Whether to prune volumes.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+
+

volume_filters

+

dictionary

+

A dictionary of filter values used for selecting volumes to delete.

+

See the podman documentation for more information on possible filters.

+
+
+
+

Examples

+
- name: Prune containers older than 24h
+  containers.podman.podman_prune:
+      containers: true
+      containers_filters:
+          # only consider containers created more than 24 hours ago
+          until: 24h
+
+- name: Prune everything
+  containers.podman.podman_prune:
+      system: true
+
+- name: Prune everything (including non-dangling images)
+  containers.podman.podman_prune:
+      system: true
+      system_all: true
+      system_volumes: true
+
+
+
+
+

Return Values

+

Common return values are documented here, the following are the fields unique to this module:

+ + + + + + + + + + + + + + + + + + + + + + + +

Key

Description

+

containers

+

list / elements=string

+

List of IDs of deleted containers.

+

Returned: containers is true

+

Sample: []

+
+

images

+

list / elements=string

+

List of IDs of deleted images.

+

Returned: images is true

+

Sample: []

+
+

networks

+

list / elements=string

+

List of IDs of deleted networks.

+

Returned: networks is true

+

Sample: []

+
+

system

+

list / elements=string

+

List of ID of deleted containers, volumes, images, network and total reclaimed space

+

Returned: system is true

+

Sample: []

+
+

volumes

+

list / elements=string

+

List of IDs of deleted volumes.

+

Returned: volumes is true

+

Sample: []

+
+
+

Authors

+
    +

  • Roberto Alfieri (@rebtoor)

    • +
+
+ +
+
+ + +
+ +
+
+ +
+
+
+ ©. + + | + Powered by Sphinx 7.0.1 + & Alabaster 0.7.13 + + | + Page source +
+ + + + + + \ No newline at end of file diff --git a/docs/podman_runlabel_module.html b/docs/podman_runlabel_module.html new file mode 100644 index 00000000..c72bd83b --- /dev/null +++ b/docs/podman_runlabel_module.html @@ -0,0 +1,226 @@ + + + + + + + + + containers.podman.podman_runlabel module – Run given label from given image — Python documentation + + + + + + + + + + + + + + + + + + + +
+
+
+ + +
+ +
+

containers.podman.podman_runlabel module – Run given label from given image

+
+

Note

+

This module is part of the containers.podman collection (version 1.11.0).

+

It is not included in ansible-core. +To check whether it is installed, run ansible-galaxy collection list.

+

To install it, use: ansible-galaxy collection install containers.podman. +You need further requirements to be able to use this module, +see Requirements for details.

+

To use it in a playbook, specify: containers.podman.podman_runlabel.

+
+ +
+

Synopsis

+
    +

  • podman container runlabel runs selected label from given image

    • +
+
+
+

Requirements

+

The below requirements are needed on the host that executes this module.

+
    +

  • Podman installed on host

    • +
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + +

Parameter

Comments

+

executable

+

string

+

Path to podman executable if it is not in the $PATH on the machine running podman

+

Default: "podman"

+
+

image

+

string / required

+

Image to get the label from.

+
+

label

+

string / required

+

Label to run.

+
+
+
+

Examples

+
# What modules does for example
+- containers.podman.podman_runlabel:
+    image: docker.io/continuumio/miniconda3
+    label: INSTALL
+
+
+
+

Authors

+
    +

  • Pavel Dostal (@pdostal)

    • +
+
+ +
+
+ + +
+ +
+
+ +
+
+
+ ©. + + | + Powered by Sphinx 7.0.1 + & Alabaster 0.7.13 + + | + Page source +
+ + + + + + \ No newline at end of file