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

Merge pull request #14641 from thaJeztah/reference_layout 

updates to command-line reference layout
This commit is contained in:
Usha Mandya 2022-05-11 09:57:36 +01:00 committed by GitHub
parent 3f257d23e6 b02580bd21
commit bbc55b89ec
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 56 additions and 24 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

58
_includes/cli.md
View File

@ -2,11 +2,22 @@
{% assign controller_data = site.data[include.datafolder][include.datafile] %}
{% assign parentPath = page.path | prepend: "/" | remove: page.name %}
## Description
<br />
{{ 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 %}
@ -25,15 +37,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.
@ -50,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 %}
@ -86,8 +86,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 }}
@ -118,7 +123,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" ttitle="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: ',' %}
@ -146,7 +158,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
@ -154,9 +166,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 %}