Commit fb8b6d63 authored by Peter Hutterer's avatar Peter Hutterer
Browse files

doc: switch to using ..attribute for the variable documentation



This gives us slightly more flexibility in how we add extra information to
each variable than we have with the previous list format.
Signed-off-by: Peter Hutterer's avatarPeter Hutterer <peter.hutterer@who-t.net>
parent 80f60289
......@@ -143,30 +143,57 @@
# - ``image:`` do not override
# - ``script:`` do not override
#
# **Variables required:**
# **Variables:**
#
{% if not version %}
# - ``FDO_DISTRIBUTION_VERSION``: the {{distribution}} version to build, e.g. {{version_examples|join(', ')}}
# .. attribute:: FDO_DISTRIBUTION_VERSION
#
# **This variable is required**
#
# The {{distribution}} version to build, e.g. {{version_examples|join(', ')}}.
#
{% endif %}
# - ``FDO_DISTRIBUTION_TAG``: string to identify the image in the registry
#
# **Optional variables:**
#
# - ``FDO_UPSTREAM_REPO``: the GitLab project path to the upstream project
# - ``FDO_REPO_SUFFIX``: the repository name suffix to use, see below.
# - ``FDO_DISTRIBUTION_PACKAGES``: packages to install as a space-separated single string, e.g. "curl wget"
# - ``FDO_DISTRIBUTION_EXEC``: an executable run after the installation of the ``FDO_DISTRIBUTION_PACKAGES``
# - ``FDO_FORCE_REBUILD``: if set, the image will be built even if it exists in the registry already
# - ``FDO_EXPIRES_AFTER``: if set enables an expiration time on the image to
# aid the garbage collector in deciding when an image can be removed. This
# should be set for temporary images that are not intended to be kept
# forever. Allowed values are e.g. ``1h`` (one hour), ``2d`` (two days) or
# ``3w`` (three weeks).
# - ``FDO_CACHE_DIR``: If set, the given directory is mounted as ``/cache``
# when ``FDO_DISTRIBUTION_EXEC`` is run. This can allow for passing of
# cache values between build jobs (if run on the same runner). You should
# not usually need to set this, it defaults to ``/cache`` from the host
# and thus enables cache sharing by default.
# .. attribute:: FDO_DISTRIBUTION_TAG
#
# **This variable is required**
#
# String to identify the image in the registry.
#
# .. attribute:: FDO_UPSTREAM_REPO
#
# The GitLab project path to the upstream project
#
# .. attribute:: FDO_REPO_SUFFIX
#
# The repository name suffix to use, see below.
#
# .. attribute:: FDO_DISTRIBUTION_PACKAGES
#
# Packages to install as a space-separated single string, e.g. "curl wget"
#
# .. attribute:: FDO_DISTRIBUTION_EXEC
#
# An executable run after the installation of the :attr:`FDO_DISTRIBUTION_PACKAGES`
#
# .. attribute:: FDO_FORCE_REBUILD
#
# If set, the image will be built even if it exists in the registry already
#
# .. attribute:: FDO_EXPIRES_AFTER
#
# If set, enables an expiration time on the image to
# aid the garbage collector in deciding when an image can be removed. This
# should be set for temporary images that are not intended to be kept
# forever. Allowed values are e.g. ``1h`` (one hour), ``2d`` (two days) or
# ``3w`` (three weeks).
#
# .. attribute:: FDO_CACHE_DIR
#
# If set, the given directory is mounted as ``/cache``
# when ``FDO_DISTRIBUTION_EXEC`` is run. This can allow for passing of
# cache values between build jobs (if run on the same runner). You should
# not usually need to set this, it defaults to ``/cache`` from the host
# and thus enables cache sharing by default.
#
# The resulting image will be pushed to the local registry.
#
......@@ -503,19 +530,33 @@
#
# This template sets ``image:`` to the generated image. You may override this.
#
# **Variables required:**
# **Variables:**
#
{% if not version %}
# - ``FDO_DISTRIBUTION_VERSION``: the {{distribution}} version to fetch, e.g. {{version_examples|join(', ')}}
# .. attribute:: FDO_DISTRIBUTION_VERSION
#
# **This variable is required**
#
# The {{distribution}} version to build, e.g. {{version_examples|join(', ')}}.
#
{% endif %}
# - ``FDO_DISTRIBUTION_TAG``: string to identify the image in the registry
# .. attribute:: FDO_DISTRIBUTION_TAG
#
# **Variables provided by this template:**
# **This variable is required**
#
# - ``FDO_DISTRIBUTION_IMAGE``: path to the registry image
# - ``FDO_DISTRIBUTION_NAME``: set to "{{distribution}}"
# String to identify the image in the registry.
#
# Variables provided by this template should be considered read-only.
# .. attribute:: FDO_DISTRIBUTION_IMAGE
#
# **This variable is set by this template and should be treated as read-only**
#
# Path to the registry image
#
# .. attribute:: FDO_DISTRIBUTION_NAME
#
# **This variable is set by this template and should be treated as read-only**
#
# Set to the string "{{distribution}}"
#
# .. note:: If you used ``FDO_REPO_SUFFIX`` when building the container, use
# ``.fdo.suffixed-image@{{distribution}}`` instead.
......@@ -541,15 +582,31 @@
#
# This template sets ``image:`` to the generated image. You may override this.
#
# **Variables required:**
# **Variables:**
#
# .. attribute:: FDO_REPO_SUFFIX
#
# **This variable is required**
#
# The repository name suffix
#
# .. attribute:: FDO_DISTRIBUTION_TAG
#
# **This variable is required**
#
# String to identify the image in the registry.
#
# .. attribute:: FDO_DISTRIBUTION_IMAGE
#
# **This variable is set by this template and should be treated as read-only**
#
# Path to the registry image
#
# - ``FDO_REPO_SUFFIX``: the repository name suffix
# - ``FDO_DISTRIBUTION_TAG``: string to identify the image in the registry
# .. attribute:: FDO_DISTRIBUTION_NAME
#
# **Variables provided by this template:**
# **This variable is set by this template and should be treated as read-only**
#
# - ``FDO_DISTRIBUTION_IMAGE``: path to the registry image
# - ``FDO_DISTRIBUTION_NAME``: set to "{{distribution}}"
# Set to the string "{{distribution}}"
#
#
# Variables provided by this template should be considered read-only.
......
......@@ -136,27 +136,49 @@
# - ``image:`` do not override
# - ``script:`` do not override
#
# **Variables required:**
#
# - ``FDO_DISTRIBUTION_TAG``: string to identify the image in the registry
#
# **Optional variables:**
#
# - ``FDO_UPSTREAM_REPO``: the GitLab project path to the upstream project
# - ``FDO_REPO_SUFFIX``: the repository name suffix to use, see below.
# - ``FDO_DISTRIBUTION_PACKAGES``: packages to install as a space-separated single string, e.g. "curl wget"
# - ``FDO_DISTRIBUTION_EXEC``: an executable run after the installation of the ``FDO_DISTRIBUTION_PACKAGES``
# - ``FDO_FORCE_REBUILD``: if set, the image will be built even if it exists in the registry already
# - ``FDO_EXPIRES_AFTER``: if set enables an expiration time on the image to
# aid the garbage collector in deciding when an image can be removed. This
# should be set for temporary images that are not intended to be kept
# forever. Allowed values are e.g. ``1h`` (one hour), ``2d`` (two days) or
# ``3w`` (three weeks).
# - ``FDO_CACHE_DIR``: If set, the given directory is mounted as ``/cache``
# when ``FDO_DISTRIBUTION_EXEC`` is run. This can allow for passing of
# cache values between build jobs (if run on the same runner). You should
# not usually need to set this, it defaults to ``/cache`` from the host
# and thus enables cache sharing by default.
# **Variables:**
#
# .. attribute:: FDO_DISTRIBUTION_TAG
#
# **This variable is required**
#
# String to identify the image in the registry.
#
# .. attribute:: FDO_UPSTREAM_REPO
#
# The GitLab project path to the upstream project
#
# .. attribute:: FDO_REPO_SUFFIX
#
# The repository name suffix to use, see below.
#
# .. attribute:: FDO_DISTRIBUTION_PACKAGES
#
# Packages to install as a space-separated single string, e.g. "curl wget"
#
# .. attribute:: FDO_DISTRIBUTION_EXEC
#
# An executable run after the installation of the :attr:`FDO_DISTRIBUTION_PACKAGES`
#
# .. attribute:: FDO_FORCE_REBUILD
#
# If set, the image will be built even if it exists in the registry already
#
# .. attribute:: FDO_EXPIRES_AFTER
#
# If set, enables an expiration time on the image to
# aid the garbage collector in deciding when an image can be removed. This
# should be set for temporary images that are not intended to be kept
# forever. Allowed values are e.g. ``1h`` (one hour), ``2d`` (two days) or
# ``3w`` (three weeks).
#
# .. attribute:: FDO_CACHE_DIR
#
# If set, the given directory is mounted as ``/cache``
# when ``FDO_DISTRIBUTION_EXEC`` is run. This can allow for passing of
# cache values between build jobs (if run on the same runner). You should
# not usually need to set this, it defaults to ``/cache`` from the host
# and thus enables cache sharing by default.
#
# The resulting image will be pushed to the local registry.
#
......@@ -281,16 +303,25 @@
#
# This template sets ``image:`` to the generated image. You may override this.
#
# **Variables required:**
# **Variables:**
#
# - ``FDO_DISTRIBUTION_TAG``: string to identify the image in the registry
# .. attribute:: FDO_DISTRIBUTION_TAG
#
# **Variables provided by this template:**
# **This variable is required**
#
# - ``FDO_DISTRIBUTION_IMAGE``: path to the registry image
# - ``FDO_DISTRIBUTION_NAME``: set to "alpine"
# String to identify the image in the registry.
#
# Variables provided by this template should be considered read-only.
# .. attribute:: FDO_DISTRIBUTION_IMAGE
#
# **This variable is set by this template and should be treated as read-only**
#
# Path to the registry image
#
# .. attribute:: FDO_DISTRIBUTION_NAME
#
# **This variable is set by this template and should be treated as read-only**
#
# Set to the string "alpine"
#
# .. note:: If you used ``FDO_REPO_SUFFIX`` when building the container, use
# ``.fdo.suffixed-image@alpine`` instead.
......@@ -308,15 +339,31 @@
#
# This template sets ``image:`` to the generated image. You may override this.
#
# **Variables required:**
# **Variables:**
#
# .. attribute:: FDO_REPO_SUFFIX
#
# **This variable is required**
#
# The repository name suffix
#
# .. attribute:: FDO_DISTRIBUTION_TAG
#
# **This variable is required**
#
# String to identify the image in the registry.
#
# .. attribute:: FDO_DISTRIBUTION_IMAGE
#
# **This variable is set by this template and should be treated as read-only**
#
# Path to the registry image
#
# - ``FDO_REPO_SUFFIX``: the repository name suffix
# - ``FDO_DISTRIBUTION_TAG``: string to identify the image in the registry
# .. attribute:: FDO_DISTRIBUTION_NAME
#
# **Variables provided by this template:**
# **This variable is set by this template and should be treated as read-only**
#
# - ``FDO_DISTRIBUTION_IMAGE``: path to the registry image
# - ``FDO_DISTRIBUTION_NAME``: set to "alpine"
# Set to the string "alpine"
#
#
# Variables provided by this template should be considered read-only.
......
......@@ -136,27 +136,49 @@
# - ``image:`` do not override
# - ``script:`` do not override
#
# **Variables required:**
#
# - ``FDO_DISTRIBUTION_TAG``: string to identify the image in the registry
#
# **Optional variables:**
#
# - ``FDO_UPSTREAM_REPO``: the GitLab project path to the upstream project
# - ``FDO_REPO_SUFFIX``: the repository name suffix to use, see below.
# - ``FDO_DISTRIBUTION_PACKAGES``: packages to install as a space-separated single string, e.g. "curl wget"
# - ``FDO_DISTRIBUTION_EXEC``: an executable run after the installation of the ``FDO_DISTRIBUTION_PACKAGES``
# - ``FDO_FORCE_REBUILD``: if set, the image will be built even if it exists in the registry already
# - ``FDO_EXPIRES_AFTER``: if set enables an expiration time on the image to
# aid the garbage collector in deciding when an image can be removed. This
# should be set for temporary images that are not intended to be kept
# forever. Allowed values are e.g. ``1h`` (one hour), ``2d`` (two days) or
# ``3w`` (three weeks).
# - ``FDO_CACHE_DIR``: If set, the given directory is mounted as ``/cache``
# when ``FDO_DISTRIBUTION_EXEC`` is run. This can allow for passing of
# cache values between build jobs (if run on the same runner). You should
# not usually need to set this, it defaults to ``/cache`` from the host
# and thus enables cache sharing by default.
# **Variables:**
#
# .. attribute:: FDO_DISTRIBUTION_TAG
#
# **This variable is required**
#
# String to identify the image in the registry.
#
# .. attribute:: FDO_UPSTREAM_REPO
#
# The GitLab project path to the upstream project
#
# .. attribute:: FDO_REPO_SUFFIX
#
# The repository name suffix to use, see below.
#
# .. attribute:: FDO_DISTRIBUTION_PACKAGES
#
# Packages to install as a space-separated single string, e.g. "curl wget"
#
# .. attribute:: FDO_DISTRIBUTION_EXEC
#
# An executable run after the installation of the :attr:`FDO_DISTRIBUTION_PACKAGES`
#
# .. attribute:: FDO_FORCE_REBUILD
#
# If set, the image will be built even if it exists in the registry already
#
# .. attribute:: FDO_EXPIRES_AFTER
#
# If set, enables an expiration time on the image to
# aid the garbage collector in deciding when an image can be removed. This
# should be set for temporary images that are not intended to be kept
# forever. Allowed values are e.g. ``1h`` (one hour), ``2d`` (two days) or
# ``3w`` (three weeks).
#
# .. attribute:: FDO_CACHE_DIR
#
# If set, the given directory is mounted as ``/cache``
# when ``FDO_DISTRIBUTION_EXEC`` is run. This can allow for passing of
# cache values between build jobs (if run on the same runner). You should
# not usually need to set this, it defaults to ``/cache`` from the host
# and thus enables cache sharing by default.
#
# The resulting image will be pushed to the local registry.
#
......@@ -268,16 +290,25 @@
#
# This template sets ``image:`` to the generated image. You may override this.
#
# **Variables required:**
# **Variables:**
#
# - ``FDO_DISTRIBUTION_TAG``: string to identify the image in the registry
# .. attribute:: FDO_DISTRIBUTION_TAG
#
# **Variables provided by this template:**
# **This variable is required**
#
# - ``FDO_DISTRIBUTION_IMAGE``: path to the registry image
# - ``FDO_DISTRIBUTION_NAME``: set to "arch"
# String to identify the image in the registry.
#
# Variables provided by this template should be considered read-only.
# .. attribute:: FDO_DISTRIBUTION_IMAGE
#
# **This variable is set by this template and should be treated as read-only**
#
# Path to the registry image
#
# .. attribute:: FDO_DISTRIBUTION_NAME
#
# **This variable is set by this template and should be treated as read-only**
#
# Set to the string "arch"
#
# .. note:: If you used ``FDO_REPO_SUFFIX`` when building the container, use
# ``.fdo.suffixed-image@arch`` instead.
......@@ -295,15 +326,31 @@
#
# This template sets ``image:`` to the generated image. You may override this.
#
# **Variables required:**
# **Variables:**
#
# .. attribute:: FDO_REPO_SUFFIX
#
# **This variable is required**
#
# The repository name suffix
#
# .. attribute:: FDO_DISTRIBUTION_TAG
#
# **This variable is required**
#
# String to identify the image in the registry.
#
# .. attribute:: FDO_DISTRIBUTION_IMAGE
#
# **This variable is set by this template and should be treated as read-only**
#
# Path to the registry image
#
# - ``FDO_REPO_SUFFIX``: the repository name suffix
# - ``FDO_DISTRIBUTION_TAG``: string to identify the image in the registry
# .. attribute:: FDO_DISTRIBUTION_NAME
#
# **Variables provided by this template:**
# **This variable is set by this template and should be treated as read-only**
#
# - ``FDO_DISTRIBUTION_IMAGE``: path to the registry image
# - ``FDO_DISTRIBUTION_NAME``: set to "arch"
# Set to the string "arch"
#
#
# Variables provided by this template should be considered read-only.
......
......@@ -136,28 +136,55 @@
# - ``image:`` do not override
# - ``script:`` do not override
#
# **Variables required:**
#
# - ``FDO_DISTRIBUTION_VERSION``: the centos version to build, e.g. 7, 8
# - ``FDO_DISTRIBUTION_TAG``: string to identify the image in the registry
#
# **Optional variables:**
#
# - ``FDO_UPSTREAM_REPO``: the GitLab project path to the upstream project
# - ``FDO_REPO_SUFFIX``: the repository name suffix to use, see below.
# - ``FDO_DISTRIBUTION_PACKAGES``: packages to install as a space-separated single string, e.g. "curl wget"
# - ``FDO_DISTRIBUTION_EXEC``: an executable run after the installation of the ``FDO_DISTRIBUTION_PACKAGES``
# - ``FDO_FORCE_REBUILD``: if set, the image will be built even if it exists in the registry already
# - ``FDO_EXPIRES_AFTER``: if set enables an expiration time on the image to
# aid the garbage collector in deciding when an image can be removed. This
# should be set for temporary images that are not intended to be kept
# forever. Allowed values are e.g. ``1h`` (one hour), ``2d`` (two days) or
# ``3w`` (three weeks).
# - ``FDO_CACHE_DIR``: If set, the given directory is mounted as ``/cache``
# when ``FDO_DISTRIBUTION_EXEC`` is run. This can allow for passing of
# cache values between build jobs (if run on the same runner). You should
# not usually need to set this, it defaults to ``/cache`` from the host
# and thus enables cache sharing by default.
# **Variables:**
#
# .. attribute:: FDO_DISTRIBUTION_VERSION
#
# **This variable is required**
#
# The centos version to build, e.g. 7, 8.
#
# .. attribute:: FDO_DISTRIBUTION_TAG
#
# **This variable is required**
#
# String to identify the image in the registry.
#
# .. attribute:: FDO_UPSTREAM_REPO
#
# The GitLab project path to the upstream project
#
# .. attribute:: FDO_REPO_SUFFIX
#
# The repository name suffix to use, see below.
#
# .. attribute:: FDO_DISTRIBUTION_PACKAGES
#
# Packages to install as a space-separated single string, e.g. "curl wget"
#
# .. attribute:: FDO_DISTRIBUTION_EXEC
#
# An executable run after the installation of the :attr:`FDO_DISTRIBUTION_PACKAGES`
#
# .. attribute:: FDO_FORCE_REBUILD
#
# If set, the image will be built even if it exists in the registry already
#
# .. attribute:: FDO_EXPIRES_AFTER
#
# If set, enables an expiration time on the image to
# aid the garbage collector in deciding when an image can be removed. This
# should be set for temporary images that are not intended to be kept
# forever. Allowed values are e.g. ``1h`` (one hour), ``2d`` (two days) or
# ``3w`` (three weeks).
#
# .. attribute:: FDO_CACHE_DIR
#
# If set, the given directory is mounted as ``/cache``
# when ``FDO_DISTRIBUTION_EXEC`` is run. This can allow for passing of
# cache values between build jobs (if run on the same runner). You should
# not usually need to set this, it defaults to ``/cache`` from the host
# and thus enables cache sharing by default.
#
# The resulting image will be pushed to the local registry.
#
......@@ -268,17 +295,31 @@
#
# This template sets ``image:`` to the generated image. You may override this.
#
# **Variables required:**
# **Variables:**
#
# - ``FDO_DISTRIBUTION_VERSION``: the centos version to fetch, e.g. 7, 8
# - ``FDO_DISTRIBUTION_TAG``: string to identify the image in the registry
# .. attribute:: FDO_DISTRIBUTION_VERSION
#
# **Variables provided by this template:**
# **This variable is required**
#
# - ``FDO_DISTRIBUTION_IMAGE``: path to the registry image
# - ``FDO_DISTRIBUTION_NAME``: set to "centos"
# The centos version to build, e.g. 7, 8.
#
# Variables provided by this template should be considered read-only.
# .. attribute:: FDO_DISTRIBUTION_TAG
#
# **This variable is required**
#
# String to identify the image in the registry.
#
# .. attribute:: FDO_DISTRIBUTION_IMAGE
#
# **This variable is set by this template and should be treated as read-only**
#
# Path to the registry image
#
# .. attribute:: FDO_DISTRIBUTION_NAME
#
# **This variable is set by this template and should be treated as read-only**
#
# Set to the string "centos"
#
# .. note:: If you used ``FDO_REPO_SUFFIX`` when building the container, use
# ``.fdo.suffixed-image@centos`` instead.
......@@ -296,15 +337,31 @@
#
# This template sets ``image:`` to the generated image. You may override this.
#
# **Variables required:**
# **Variables:**
#
# .. attribute:: FDO_REPO_SUFFIX
#
# **This variable is required**
#
# The repository name suffix
#
# .. attribute:: FDO_DISTRIBUTION_TAG
#
# **This variable is required**
#
# String to identify the image in the registry.
#
# .. attribute:: FDO_DISTRIBUTION_IMAGE
#
# **This variable is set by this template and should be treated as read-only**
#
# Path to the registry image
#
# - ``FDO_REPO_SUFFIX``: the repository name suffix
# - ``FDO_DISTRIBUTION_TAG``: string to identify the image in the registry
# .. attribute:: FDO_DISTRIBUTION_NAME
#
# **Variables provided by this template:**
# **This variable is set by this template and should be treated as read-only**
#
# - ``FDO_DISTRIBUTION_IMAGE``: path to the registry image
# - ``FDO_DISTRIBUTION_NAME``: set to "centos"
# Set to the string "centos"
#
#
# Variables provided by this template should be considered read-only.
......
......@@ -136,28 +136,55 @@
# - ``image:`` do not override
# - ``script:`` do not override
#
# **Variables required:**
#
# - ``FDO_DISTRIBUTION_VERSION``: the debian version to build, e.g. stretch, sid, buster
# - ``FDO_DISTRIBUTION_TAG``: string to identify the image in the registry
#
# **Optional variables:**
#
# - ``FDO_UPSTREAM_REPO``: the GitLab project path to the upstream project
# - ``FDO_REPO_SUFFIX``: the repository name suffix to use, see below.
# - ``FDO_DISTRIBUTION_PACKAGES``: packages to install as a space-separated single string, e.g. "curl wget"
# - ``FDO_DISTRIBUTION_EXEC``: an executable run after the installation of the ``FDO_DISTRIBUTION_PACKAGES``
# - ``FDO_FORCE_REBUILD``: if set, the image will be built even if it exists in the registry already
# - ``FDO_EXPIRES_AFTER``: if set enables an expiration time on the image to
# aid the garbage collector in deciding when an image can be removed. This
# should be set for temporary images that are not intended to be kept
# forever. Allowed values are e.g. ``1h`` (one hour), ``2d`` (two days) or
# ``3w`` (three weeks).
# - ``FDO_CACHE_DIR``: If set, the given directory is mounted as ``/cache``
# when ``FDO_DISTRIBUTION_EXEC`` is run. This can allow for passing of
# cache values between build jobs (if run on the same runner). You should
# not usually need to set this, it defaults to ``/cache`` from the host
# and thus enables cache sharing by default.
# **Variables:**
#
# .. attribute:: FDO_DISTRIBUTION_VERSION
#
# **This variable is required**
#
# The debian version to build, e.g. stretch, sid, buster.
#
# .. attribute:: FDO_DISTRIBUTION_TAG
#
# **This variable is required**
#
# String to identify the image in the registry.
#
# .. attribute:: FDO_UPSTREAM_REPO
#
# The GitLab project path to the upstream project
#
# .. attribute:: FDO_REPO_SUFFIX
#
# The repository name suffix to use, see below.
#
# .. attribute:: FDO_DISTRIBUTION_PACKAGES
#
# Packages to install as a space-separated single string, e.g. "curl wget"
#
# .. attribute:: FDO_DISTRIBUTION_EXEC
#
# An executable run after the installation of the :attr:`FDO_DISTRIBUTION_PACKAGES`
#