docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

reference: hide "minimum API version" badges for old versions 

The reference pages show badges for commands and options (flags) that require
a minimum API version. While this information can be useful if an option was
added in a recent version of the Docker Engine (and API), these badges are no
longer relevant to most users if the minimum required version is quite "old".

We assume users reading these pages to be on the current version, or at most
on the version before that (which is already "unsupported"). Users running
older versions have bigger problems on their hand, so we're not accounting for
those.

So, to reduce unnecessary clutter on the page, we only show the minimum required
API version if it requires a relatively recent version of the Engine.

A new "min_api_threshold" option was added in the `_config.yml`, which specifies
the minimum required API version for which we show a badge (currently: API v1.40,
or "Docker 19.03").

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Sebastiaan van Stijn 2022-04-30 19:10:05 +02:00
parent 27355f688d
commit d468e10c68
No known key found for this signature in database
GPG Key ID: 76698F39D527CE8C
2 changed files with 41 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
_config.yml
View File

@ -19,7 +19,8 @@ lsi: false
exclude: ["_samples", "_scripts", "404.html", "datacenter", "ee", "index.html", "js/metadata.json"]
# Component versions -- address like site.docker_ce_version
# You can't have - characters in these for non-YAML reasons
# You can't have - characters in these for non-YAML reasons.
# When updating 'latest_engine_api_version', also update 'min_api_threshold' below.
latest_engine_api_version: "1.41"
docker_ce_version: "20.10"
compose_v1_version: "1.29.2"
@ -30,6 +31,25 @@ machine_version: "0.16.0"
distribution_version: "2.7"
compose_switch_version: "1.0.4"
# Options for displaying minimum API version requirements in the reference pages.
#
# The reference pages show badges for commands and options (flags) that require
# a minimum API version. While this information can be useful if an option was
# added in a recent version of the Docker Engine (and API), these badges are no
# longer relevant to most users if the minimum required version is quite "old".
#
# We assume users reading these pages to be on the current version, or at most
# on the version before that (which is already "unsupported"). Users running
# older versions have bigger problems on their hand, so we're not accounting for
# those.
#
# So, to reduce unnecessary clutter on the page, we only show the minimum required
# API version if it requires a relatively recent version of the Engine.
#
# The "min_api_threshold" option specifies the minimum required API version for
# which we show a badge (currently: API v1.40, or "Docker 19.03").
min_api_threshold: 1.40
# List of plugins to enable for local development builds. Mostly the same as
# for production, but without the "jekyll-sitemap" plugin, which is not needed
# for previewing, and excluding saves some time to build

21
_includes/cli.md
View File

@ -7,6 +7,17 @@
{{ controller_data.short | replace_relative_links: page.path }}
{% if controller_data.min_api_version %}
{% comment %}
To reduce unnecessary clutter on the page, we only show the minimum required
API version if it requires a relatively recent version of the Engine, which
is configured through the "min_api_threshold" option in _config.yml
Below, we first convert the min_api_version from a string to a number, so that
we can compare versions (see https://stackoverflow.com/a/27200972/1811501),
then compare it, to decide whether to show the "minimum required API version".
{% endcomment %}
{% assign min_api_version = controller_data.min_api_version | plus: 0 %}
{% if min_api_version >= site.min_api_threshold %}
<a href="/engine/api/v{{ controller_data.min_api_version }}/" target="_blank" rel="noopener" class="_"><span class="badge badge-info" data-toggle="tooltip" data-placement="right" title="Open the {{ controller_data.min_api_version }} API reference (in a new window)">API {{ controller_data.min_api_version }}+</span></a>&nbsp;
The client and daemon API must both be at least
@ -14,6 +25,7 @@ The client and daemon API must both be at least
to use this command. Use the `docker version` command on the client to check
your client and daemon API versions.
{% endif %}
{% endif %}
{% if controller_data.deprecated %}
@ -114,7 +126,14 @@ For example uses of this command, refer to the [examples section](#examples) bel
{% capture deprecated-badge %}{% if option.deprecated %}<a href="/engine/deprecated/" target="_blank" rel="noopener" class="_"><span class="badge badge-danger" data-toggle="tooltip" title="Read the deprecation reference (in a new window).">deprecated</span></a>{% endif %}{% endcapture %}
{% capture experimental-daemon-badge %}{% if option.experimental %}<a href="/engine/reference/commandline/dockerd/#daemon-configuration-file" target="_blank" rel="noopener" class="_"><span class="badge badge-warning" data-toggle="tooltip" title="Read about experimental daemon options (in a new window).">experimental (daemon)</span></a>{% endif %}{% endcapture %}
{% capture experimental-cli-badge %}{% if option.experimentalcli %}<a href="/engine/reference/commandline/cli/#configuration-files" target="_blank" rel="noopener" class="_"><span class="badge badge-warning" data-toggle="tooltip" title="Read about experimental CLI options (in a new window).">experimental (CLI)</span></a>{% endif %}{% endcapture %}
{% capture min-api %}{% if option.min_api_version %}<a href="/engine/api/v{{ option.min_api_version }}/" target="_blank" rel="noopener" class="_"><span class="badge badge-info" data-toggle="tooltip" title="Open the {{ controller_data.min_api_version }} API reference (in a new window)">API {{ option.min_api_version }}+</span></a>{% endif %}{%endcapture%}
{%- if option.min_api_version -%}
{% assign min_api_version = option.min_api_version | plus: 0 %}
{% if min_api_version >= site.min_api_threshold %}
{% capture min-api %}<a href="/engine/api/v{{ option.min_api_version }}/" target="_blank" rel="noopener" class="_"><span class="badge badge-info" data-toggle="tooltip" title="Open the {{ controller_data.min_api_version }} API reference (in a new window)">API {{ option.min_api_version }}+</span></a>{%endcapture%}
{%- endif -%}
{%- else -%}
{% capture min-api %}{%endcapture%}
{%- endif -%}
{% capture flag-orchestrator %}{% if option.swarm %}<span class="badge badge-info" data-toggle="tooltip" title="This option works for the Swarm orchestrator.">Swarm</span>{% endif %}{% if option.kubernetes %}<span class="badge badge-info" data-toggle="tooltip" title="This option works for the Kubernetes orchestrator.">Kubernetes</span>{% endif %}{% endcapture %}
{% capture all-badges %}{{ deprecated-badge }}{{ experimental-daemon-badge }}{{ experimental-cli-badge }}{{ min-api }}{{ flag-orchestrator }}{% endcapture %}
{% assign defaults-to-skip = "[],map[],false,0,0s,default,'',\"\"" | split: ',' %}