From 67f15b4e1985a62b4530638dfad93d9855364b2f Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Sat, 30 Apr 2022 16:08:57 +0200 Subject: [PATCH 1/7] reference: remove "enterprise_only" condition This metadata condition was used for features that were only available on Docker Enterprise Edition ("Docker EE"), and is no longer used. Signed-off-by: Sebastiaan van Stijn --- _includes/cli.md | 9 --------- 1 file changed, 9 deletions(-) diff --git a/_includes/cli.md b/_includes/cli.md index bdc07c1d28..705af60357 100644 --- a/_includes/cli.md +++ b/_includes/cli.md @@ -25,15 +25,6 @@ your client and daemon API versions. {% endif %} -{% if page.enterprise_only == true %} - -> This command is only available on Docker Enterprise Edition. -> -> Learn more about [Docker Enterprise products](/ee/supported-platforms/){: target="_blank" rel="noopener" class="_"}. -{: .important } - -{% endif %} - {% if controller_data.experimental %} > This command is experimental. From 144c8b1f8f820ee3969cab74d69d0222fc8c7953 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Sat, 30 Apr 2022 17:05:46 +0200 Subject: [PATCH 2/7] reference: remove "description" header, and use it for "extended description" The "description" header included the short description of each command. In most cases, this description was very short ("run a container"), and adding the extra header before it only was adding extra noise. This patch: - removes the top "description" header - renames the existing "extended description" header to "description" (a hidden "extended-description" anchor is added for backward compatibility) As the extended description can be long (hopefully!), there may be a long distance between the `Usage` section and the `Options` section. To help users navigate to the list of available options, an extra line is printed if an extended description is available for the command, including a link to the corresponding section: > Refer to the options section for an overview of available OPTIONS for this command. Signed-off-by: Sebastiaan van Stijn --- _includes/cli.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/_includes/cli.md b/_includes/cli.md index 705af60357..ad30639e46 100644 --- a/_includes/cli.md +++ b/_includes/cli.md @@ -2,7 +2,7 @@ {% assign controller_data = site.data[include.datafolder][include.datafile] %} {% assign parentPath = page.path | prepend: "/" | remove: page.name %} -## Description +
{{ controller_data.short | replace_relative_links: page.path }} @@ -77,8 +77,13 @@ $ {{ controller_data.usage | replace: tabChar, "" | strip }}{% if controller_dat {% endif %} {% unless controller_data.long == controller_data.short %} +{% if controller_data.options %} +Refer to the [options section](#options) for an overview of available [`OPTIONS`](#options) for this command. +{% endif %} -## Extended description +## Description + +{: name="extended-description"} {{ controller_data.long | replace_relative_links: page.path }} From 0ea7f3de72ee61cc09d968b89216cf95bc9db9d8 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Sat, 30 Apr 2022 17:08:22 +0200 Subject: [PATCH 3/7] reference: fix title on API version badges Signed-off-by: Sebastiaan van Stijn --- _includes/cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_includes/cli.md b/_includes/cli.md index ad30639e46..49b3ffebbc 100644 --- a/_includes/cli.md +++ b/_includes/cli.md @@ -114,7 +114,7 @@ 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%} + {% capture min-api %}{% if option.min_api_version %}API {{ option.min_api_version }}+{% endif %}{%endcapture%} {% 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: ',' %} From a984ba10af06e0f0fd51aa2760403677d51add64 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Sat, 30 Apr 2022 17:10:46 +0200 Subject: [PATCH 4/7] reference: re-format markdown table in source Should make no change in the rendered output, but my IDE didn't like it not being well-formed :D Signed-off-by: Sebastiaan van Stijn --- _includes/cli.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/_includes/cli.md b/_includes/cli.md index 49b3ffebbc..ff89208032 100644 --- a/_includes/cli.md +++ b/_includes/cli.md @@ -150,9 +150,9 @@ For example uses of this command, refer to the [examples section](#examples) bel {% capture parentdatafile %}{{ controller_data.plink | remove_first: ".yaml" }}{% endcapture %} {% capture parentDesc %}{{ site.data[include.datafolder][parentdatafile].short }}{% endcapture %} -| Command | Description | -| ------- | ----------- | -| [{{ controller_data.pname }}]({{parentPath}}{{ parentfile }}/) | {{ parentDesc }}| +| Command | Description | +|:---------------------------------------------------------------|:-----------------| +| [{{ controller_data.pname }}]({{parentPath}}{{ parentfile }}/) | {{ parentDesc }} | {% endunless %} {% endif %} From 27355f688d29c4aebe9222c73be12706c74d26f2 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Sat, 30 Apr 2022 17:16:57 +0200 Subject: [PATCH 5/7] reference: omit "parent command" section for "docker" The "parent command" can be useful if the page describes a subcommand, but generally having a link to `docker` may not provide much value. This patch omits the "parent command" section if the parent command is the `docker` command itself. Signed-off-by: Sebastiaan van Stijn --- _includes/cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_includes/cli.md b/_includes/cli.md index ff89208032..91f9ea6fd3 100644 --- a/_includes/cli.md +++ b/_includes/cli.md @@ -142,7 +142,7 @@ For example uses of this command, refer to the [examples section](#examples) bel {% endif %} {% if controller_data.pname %} -{% unless controller_data.pname == include.datafile %} +{% unless controller_data.pname == include.datafile or controller_data.pname == "docker" %} ## Parent command From d468e10c6807715ea229dfe7ef2d3eec2ce7ca9d Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Sat, 30 Apr 2022 19:10:05 +0200 Subject: [PATCH 6/7] 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: ',' %} From b02580bd21edf46baaf91629cec82e8344f743a3 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Sat, 30 Apr 2022 19:21:59 +0200 Subject: [PATCH 7/7] reference: update description for experimental cli features Experimental CLI features are enabled by default since docker 20.10, so the instructions for enabling the features were no longer needed. Also tweaked the description a bit to align how we describe experimental features elsewhere. Signed-off-by: Sebastiaan van Stijn --- _includes/cli.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/_includes/cli.md b/_includes/cli.md index ce81a3dfa2..cd4e314d8f 100644 --- a/_includes/cli.md +++ b/_includes/cli.md @@ -53,14 +53,11 @@ your client and daemon API versions. {% if controller_data.experimentalcli %} -> This command is experimental on the Docker client. +> This command is experimental. > -> **It should not be used in production environments.** -> -> To enable experimental features in the Docker CLI, edit the -> [config.json](/engine/reference/commandline/cli/#configuration-files) -> and set `experimental` to `enabled`. You can go [here](https://docs.docker.com/engine/reference/commandline/cli/#experimental-features) -> for more information. +> [Experimental features](https://docs.docker.com/engine/reference/commandline/cli/#experimental-features) +> are intended for testing and feedback as their functionality or UX may change +> between releases without warning or can be removed entirely in a future release. {: .important } {% endif %}