From d468e10c6807715ea229dfe7ef2d3eec2ce7ca9d Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Sat, 30 Apr 2022 19:10:05 +0200 Subject: [PATCH] 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 --- _config.yml | 22 +++++++++++++++++++++- _includes/cli.md | 21 ++++++++++++++++++++- 2 files changed, 41 insertions(+), 2 deletions(-) diff --git a/_config.yml b/_config.yml index 5ecc307f57..d9dc2d275a 100644 --- a/_config.yml +++ b/_config.yml @@ -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 diff --git a/_includes/cli.md b/_includes/cli.md index 91f9ea6fd3..ce81a3dfa2 100644 --- a/_includes/cli.md +++ b/_includes/cli.md @@ -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 %} API {{ controller_data.min_api_version }}+  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 %}deprecated{% endif %}{% endcapture %} {% capture experimental-daemon-badge %}{% if option.experimental %}experimental (daemon){% endif %}{% endcapture %} {% capture experimental-cli-badge %}{% if option.experimentalcli %}experimental (CLI){% endif %}{% endcapture %} - {% capture min-api %}{% if option.min_api_version %}API {{ option.min_api_version }}+{% 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 %}API {{ option.min_api_version }}+{%endcapture%} + {%- endif -%} + {%- else -%} + {% capture min-api %}{%endcapture%} + {%- endif -%} {% capture flag-orchestrator %}{% if option.swarm %}Swarm{% endif %}{% if option.kubernetes %}Kubernetes{% 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: ',' %}