yamldocs: various improvements by thaJeztah · Pull Request #3034 · docker/cli

thaJeztah · 2021-03-31T23:17:41Z

Changes I made when working on docker/buildx#91. Still lots of things to clean up, but thought it didn't hurt to at least take some of them

make sure the target directory is created if missing
add support for custom ID's in headings through <a> tags (e.g.
<a name=heading2></a>). This allows use of custom anchors that
work both on GitHub (GFM doesn't support extended MarkDown), and
in Jekyll (which does).
add code to cleanup markdown for use in our docs:
- remove absolute URLs to https://docs.docker.com
- remove tabs in MarkDown, and convert them to 4 spaces. This
  prevents the YAML conversion from switching between "short"
  and "long" syntax. Tabs in code examples also don't always
  work well, so using spaces doesn't hurt for that.
refactor some code for readability, and to be less "hacky" (still
lots to be improved though)

thaJeztah · 2021-05-25T11:53:12Z

@silvin-lubecki ptal 🤗

codecov-commenter · 2021-07-09T08:07:07Z

Codecov Report

Merging #3034 (b86f513) into master (13e4a09) will decrease coverage by 0.57%.
The diff coverage is 18.39%.

@@            Coverage Diff             @@
##           master    #3034      +/-   ##
==========================================
- Coverage   58.58%   58.00%   -0.58%     
==========================================
  Files         299      302       +3     
  Lines       21502    21743     +241     
==========================================
+ Hits        12597    12613      +16     
- Misses       7983     8207     +224     
- Partials      922      923       +1

thaJeztah · 2021-07-13T10:53:50Z

Diff in generated yaml with this change;

Details

diff --git a/docs/yaml/gen-before/docker_attach.yaml b/docs/yaml/gen-after/docker_attach.yaml
index 6334682a9..86204e507 100644
--- a/docs/yaml/gen-before/docker_attach.yaml
+++ b/docs/yaml/gen-after/docker_attach.yaml
@@ -1,5 +1,6 @@
 command: docker attach
-short: Attach local standard input, output, and error streams to a running container
+short: |
+  Attach local standard input, output, and error streams to a running container
 long: |-
   Use `docker attach` to attach your terminal's standard input, output, and error
   (or any combination of the three) to a running container using the container's
diff --git a/docs/yaml/gen-before/docker_build.yaml b/docs/yaml/gen-after/docker_build.yaml
index a18af2356..e23a85a41 100644
--- a/docs/yaml/gen-before/docker_build.yaml
+++ b/docs/yaml/gen-after/docker_build.yaml
@@ -273,8 +273,7 @@ options:
 - option: network
   value_type: string
   default_value: default
-  description: |
-    Set the networking mode for the RUN instructions during build
+  description: Set the networking mode for the RUN instructions during build
   deprecated: false
   min_api_version: "1.25"
   experimental: false
@@ -682,7 +681,7 @@ examples: |-
   $ docker build --build-arg HTTP_PROXY .

-  This is similar to how `docker run -e` works. Refer to the [`docker run` documentation](https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file)
+  This is similar to how `docker run -e` works. Refer to the [`docker run` documentation](/engine/reference/commandline/run/#set-environment-variables--e---env---env-file)
   for more information.
 
   ### Optional security options (--security-opt)
@@ -891,7 +890,7 @@ examples: |-
 
   For most use cases, multi-stage builds are a better alternative, as they give more
   fine-grained control over your build, and can take advantage of future
-  optimizations in the builder. Refer to the [use multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/)
+  optimizations in the builder. Refer to the [use multi-stage builds](/develop/develop-images/multistage-build/)
   section in the userguide for more information.
 
 
diff --git a/docs/yaml/gen-before/docker_builder_build.yaml b/docs/yaml/gen-after/docker_builder_build.yaml
index 30b108b6d..a7780f386 100644
--- a/docs/yaml/gen-before/docker_builder_build.yaml
+++ b/docs/yaml/gen-after/docker_builder_build.yaml
@@ -165,8 +165,7 @@ options:
 - option: network
   value_type: string
   default_value: default
-  description: |
-    Set the networking mode for the RUN instructions during build
+  description: Set the networking mode for the RUN instructions during build
   deprecated: false
   min_api_version: "1.25"
   experimental: false
diff --git a/docs/yaml/gen-before/docker_config_create.yaml b/docs/yaml/gen-after/docker_config_create.yaml
index a06401974..1fab9ab87 100644
--- a/docs/yaml/gen-before/docker_config_create.yaml
+++ b/docs/yaml/gen-after/docker_config_create.yaml
@@ -3,13 +3,13 @@ short: Create a config from a file or STDIN
 long: |-
   Creates a config using standard input or from a file for the config content.
 
-  For detailed information about using configs, refer to [store configuration data using Docker Configs](https://docs.docker.com/engine/swarm/configs/).
+  For detailed information about using configs, refer to [store configuration data using Docker Configs](/engine/swarm/configs/).
 
   > **Note**
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker config create [OPTIONS] CONFIG file|-
 pname: docker config
diff --git a/docs/yaml/gen-before/docker_config_inspect.yaml b/docs/yaml/gen-after/docker_config_inspect.yaml
index aae83ba95..00d170e36 100644
--- a/docs/yaml/gen-before/docker_config_inspect.yaml
+++ b/docs/yaml/gen-after/docker_config_inspect.yaml
@@ -9,13 +9,13 @@ long: |-
   Go's [text/template](http://golang.org/pkg/text/template/) package
   describes all the details of the format.
 
-  For detailed information about using configs, refer to [store configuration data using Docker Configs](https://docs.docker.com/engine/swarm/configs/).
+  For detailed information about using configs, refer to [store configuration data using Docker Configs](/engine/swarm/configs/).
 
   > **Note**
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker config inspect [OPTIONS] CONFIG [CONFIG...]
 pname: docker config
diff --git a/docs/yaml/gen-before/docker_config_ls.yaml b/docs/yaml/gen-after/docker_config_ls.yaml
index b12b15846..bdfe6e040 100644
--- a/docs/yaml/gen-before/docker_config_ls.yaml
+++ b/docs/yaml/gen-after/docker_config_ls.yaml
@@ -4,13 +4,13 @@ short: List configs
 long: |-
   Run this command on a manager node to list the configs in the swarm.
 
-  For detailed information about using configs, refer to [store configuration data using Docker Configs](https://docs.docker.com/engine/swarm/configs/).
+  For detailed information about using configs, refer to [store configuration data using Docker Configs](/engine/swarm/configs/).
 
   > **Note**
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker config ls [OPTIONS]
 pname: docker config
diff --git a/docs/yaml/gen-before/docker_config_rm.yaml b/docs/yaml/gen-after/docker_config_rm.yaml
index 317784005..c31b7ea70 100644
--- a/docs/yaml/gen-before/docker_config_rm.yaml
+++ b/docs/yaml/gen-after/docker_config_rm.yaml
@@ -4,13 +4,13 @@ short: Remove one or more configs
 long: |-
   Removes the specified configs from the swarm.
 
-  For detailed information about using configs, refer to [store configuration data using Docker Configs](https://docs.docker.com/engine/swarm/configs/).
+  For detailed information about using configs, refer to [store configuration data using Docker Configs](/engine/swarm/configs/).
 
   > **Note**
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker config rm CONFIG [CONFIG...]
 pname: docker config
diff --git a/docs/yaml/gen-before/docker_container_attach.yaml b/docs/yaml/gen-after/docker_container_attach.yaml
index 95b4d3ede..6543aa272 100644
--- a/docs/yaml/gen-before/docker_container_attach.yaml
+++ b/docs/yaml/gen-after/docker_container_attach.yaml
@@ -1,6 +1,8 @@
 command: docker container attach
-short: Attach local standard input, output, and error streams to a running container
-long: Attach local standard input, output, and error streams to a running container
+short: |
+  Attach local standard input, output, and error streams to a running container
+long: |
+  Attach local standard input, output, and error streams to a running container
 usage: docker container attach [OPTIONS] CONTAINER
 pname: docker container
 plink: docker_container.yaml
diff --git a/docs/yaml/gen-before/docker_container_create.yaml b/docs/yaml/gen-after/docker_container_create.yaml
index ece16dca1..da8af4e00 100644
--- a/docs/yaml/gen-before/docker_container_create.yaml
+++ b/docs/yaml/gen-after/docker_container_create.yaml
@@ -371,8 +371,7 @@ options:
 - option: health-timeout
   value_type: duration
   default_value: 0s
-  description: |
-    Maximum time to allow one check to run (ms|s|m|h) (default 0s)
+  description: Maximum time to allow one check to run (ms|s|m|h) (default 0s)
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -420,8 +419,7 @@ options:
 - option: io-maxbandwidth
   value_type: bytes
   default_value: "0"
-  description: |
-    Maximum IO bandwidth limit for the system drive (Windows only)
+  description: Maximum IO bandwidth limit for the system drive (Windows only)
   deprecated: false
   experimental: false
   experimentalcli: false
diff --git a/docs/yaml/gen-before/docker_container_run.yaml b/docs/yaml/gen-after/docker_container_run.yaml
index e98cfeec6..48acc8123 100644
--- a/docs/yaml/gen-before/docker_container_run.yaml
+++ b/docs/yaml/gen-after/docker_container_run.yaml
@@ -389,8 +389,7 @@ options:
 - option: health-timeout
   value_type: duration
   default_value: 0s
-  description: |
-    Maximum time to allow one check to run (ms|s|m|h) (default 0s)
+  description: Maximum time to allow one check to run (ms|s|m|h) (default 0s)
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -438,8 +437,7 @@ options:
 - option: io-maxbandwidth
   value_type: bytes
   default_value: "0"
-  description: |
-    Maximum IO bandwidth limit for the system drive (Windows only)
+  description: Maximum IO bandwidth limit for the system drive (Windows only)
   deprecated: false
   experimental: false
   experimentalcli: false
diff --git a/docs/yaml/gen-before/docker_create.yaml b/docs/yaml/gen-after/docker_create.yaml
index fdf654da2..3897fcfe3 100644
--- a/docs/yaml/gen-before/docker_create.yaml
+++ b/docs/yaml/gen-after/docker_create.yaml
@@ -382,8 +382,7 @@ options:
 - option: health-timeout
   value_type: duration
   default_value: 0s
-  description: |
-    Maximum time to allow one check to run (ms|s|m|h) (default 0s)
+  description: Maximum time to allow one check to run (ms|s|m|h) (default 0s)
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -431,8 +430,7 @@ options:
 - option: io-maxbandwidth
   value_type: bytes
   default_value: "0"
-  description: |
-    Maximum IO bandwidth limit for the system drive (Windows only)
+  description: Maximum IO bandwidth limit for the system drive (Windows only)
   deprecated: false
   experimental: false
   experimentalcli: false
diff --git a/docs/yaml/gen-before/docker_export.yaml b/docs/yaml/gen-after/docker_export.yaml
index 50520019b..83ed2e9a5 100644
--- a/docs/yaml/gen-before/docker_export.yaml
+++ b/docs/yaml/gen-after/docker_export.yaml
@@ -6,7 +6,7 @@ long: |-
   the container, `docker export` will export the contents of the *underlying*
   directory, not the contents of the volume.
 
-  Refer to [Backup, restore, or migrate data volumes](https://docs.docker.com/storage/volumes/#backup-restore-or-migrate-data-volumes)
+  Refer to [Backup, restore, or migrate data volumes](/storage/volumes/#backup-restore-or-migrate-data-volumes)
   in the user guide for examples on exporting data in a volume.
 usage: docker export [OPTIONS] CONTAINER
 pname: docker
diff --git a/docs/yaml/gen-before/docker_image_build.yaml b/docs/yaml/gen-after/docker_image_build.yaml
index f203b67f3..6c34f1b00 100644
--- a/docs/yaml/gen-before/docker_image_build.yaml
+++ b/docs/yaml/gen-after/docker_image_build.yaml
@@ -165,8 +165,7 @@ options:
 - option: network
   value_type: string
   default_value: default
-  description: |
-    Set the networking mode for the RUN instructions during build
+  description: Set the networking mode for the RUN instructions during build
   deprecated: false
   min_api_version: "1.25"
   experimental: false
diff --git a/docs/yaml/gen-before/docker_image_prune.yaml b/docs/yaml/gen-after/docker_image_prune.yaml
index cb717a3ae..6cd7bc68d 100644
--- a/docs/yaml/gen-before/docker_image_prune.yaml
+++ b/docs/yaml/gen-after/docker_image_prune.yaml
@@ -1,7 +1,7 @@
 command: docker image prune
 short: Remove unused images
-long: Remove all dangling images. If `-a` is specified, will also remove all images
-  not referenced by any container.
+long: |
+  Remove all dangling images. If `-a` is specified, will also remove all images not referenced by any container.
 usage: docker image prune [OPTIONS]
 pname: docker image
 plink: docker_image.yaml
diff --git a/docs/yaml/gen-before/docker_login.yaml b/docs/yaml/gen-after/docker_login.yaml
index b486de1a0..888134c38 100644
--- a/docs/yaml/gen-before/docker_login.yaml
+++ b/docs/yaml/gen-after/docker_login.yaml
@@ -61,7 +61,7 @@ examples: |-
   `docker login` requires user to use `sudo` or be `root`, except when:
 
   1.  connecting to a remote daemon, such as a `docker-machine` provisioned `docker engine`.
-  2.  user is added to the `docker` group.  This will impact the security of your system; the `docker` group is `root` equivalent.  See [Docker Daemon Attack Surface](https://docs.docker.com/engine/security/#docker-daemon-attack-surface) for details.
+  2.  user is added to the `docker` group.  This will impact the security of your system; the `docker` group is `root` equivalent.  See [Docker Daemon Attack Surface](/engine/security/#docker-daemon-attack-surface) for details.
 
   You can log into any public or private repository for which you have
   credentials.  When you log in, the command stores credentials in
diff --git a/docs/yaml/gen-before/docker_logout.yaml b/docs/yaml/gen-after/docker_logout.yaml
index 2c4f41b64..5c13401fe 100644
--- a/docs/yaml/gen-before/docker_logout.yaml
+++ b/docs/yaml/gen-after/docker_logout.yaml
@@ -1,6 +1,8 @@
 command: docker logout
 short: Log out from a Docker registry
-long: Log out from a Docker registry
+long: |-
+  Log out from a Docker registry.
+  If no server is specified, the default is defined by the daemon.
 usage: docker logout [SERVER]
 pname: docker
 plink: docker.yaml
diff --git a/docs/yaml/gen-before/docker_logs.yaml b/docs/yaml/gen-after/docker_logs.yaml
index 30de56f8d..00c533200 100644
--- a/docs/yaml/gen-before/docker_logs.yaml
+++ b/docs/yaml/gen-after/docker_logs.yaml
@@ -9,7 +9,7 @@ long: |-
   > `json-file` or `journald` logging driver.
 
   For more information about selecting and configuring logging drivers, refer to
-  [Configure logging drivers](https://docs.docker.com/config/containers/logging/configure/).
+  [Configure logging drivers](/config/containers/logging/configure/).
 
   The `docker logs --follow` command will continue streaming the new output from
   the container's `STDOUT` and `STDERR`.
diff --git a/docs/yaml/gen-before/docker_network_create.yaml b/docs/yaml/gen-after/docker_network_create.yaml
index 2bdf4522e..125c5a7ea 100644
--- a/docs/yaml/gen-before/docker_network_create.yaml
+++ b/docs/yaml/gen-after/docker_network_create.yaml
@@ -32,7 +32,7 @@ long: |-
   * `--cluster-advertise`
 
   To read more about these options and how to configure them, see ["*Get started
-  with multi-host network*"](https://docs.docker.com/engine/userguide/networking/get-started-overlay).
+  with multi-host network*"](/engine/userguide/networking/get-started-overlay).
 
   While not required, it is a good idea to install Docker Swarm to
   manage the cluster that makes up your network. Swarm provides sophisticated
@@ -58,7 +58,7 @@ long: |-
   need more than 256 IP addresses, do not increase the IP block size. You can
   either use `dnsrr` endpoint mode with an external load balancer, or use multiple
   smaller overlay networks. See
-  [Configure service discovery](https://docs.docker.com/engine/swarm/networking/#configure-service-discovery)
+  [Configure service discovery](/engine/swarm/networking/#configure-service-discovery)
   for more information about different endpoint modes.
 usage: docker network create [OPTIONS] NETWORK
 pname: docker network
diff --git a/docs/yaml/gen-before/docker_node_demote.yaml b/docs/yaml/gen-after/docker_node_demote.yaml
index defa899a8..b034e4e88 100644
--- a/docs/yaml/gen-before/docker_node_demote.yaml
+++ b/docs/yaml/gen-after/docker_node_demote.yaml
@@ -7,7 +7,7 @@ long: |-
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the [Swarm mode
-  > section](https://docs.docker.com/engine/swarm/) in the documentation.
+  > section](/engine/swarm/) in the documentation.
 usage: docker node demote NODE [NODE...]
 pname: docker node
 plink: docker_node.yaml
diff --git a/docs/yaml/gen-before/docker_node_inspect.yaml b/docs/yaml/gen-after/docker_node_inspect.yaml
index 641e72976..99f842572 100644
--- a/docs/yaml/gen-before/docker_node_inspect.yaml
+++ b/docs/yaml/gen-after/docker_node_inspect.yaml
@@ -11,7 +11,7 @@ long: |-
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker node inspect [OPTIONS] self|NODE [NODE...]
 pname: docker node
diff --git a/docs/yaml/gen-before/docker_node_ls.yaml b/docs/yaml/gen-after/docker_node_ls.yaml
index 1bbd100ac..710df07ba 100644
--- a/docs/yaml/gen-before/docker_node_ls.yaml
+++ b/docs/yaml/gen-after/docker_node_ls.yaml
@@ -10,7 +10,7 @@ long: |-
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker node ls [OPTIONS]
 pname: docker node
diff --git a/docs/yaml/gen-before/docker_node_promote.yaml b/docs/yaml/gen-after/docker_node_promote.yaml
index dc72a135c..c06f70f81 100644
--- a/docs/yaml/gen-before/docker_node_promote.yaml
+++ b/docs/yaml/gen-after/docker_node_promote.yaml
@@ -7,7 +7,7 @@ long: |-
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker node promote NODE [NODE...]
 pname: docker node
diff --git a/docs/yaml/gen-before/docker_node_ps.yaml b/docs/yaml/gen-after/docker_node_ps.yaml
index d6ff36423..6e02fa36a 100644
--- a/docs/yaml/gen-before/docker_node_ps.yaml
+++ b/docs/yaml/gen-after/docker_node_ps.yaml
@@ -9,7 +9,7 @@ long: |-
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker node ps [OPTIONS] [NODE...]
 pname: docker node
diff --git a/docs/yaml/gen-before/docker_node_rm.yaml b/docs/yaml/gen-after/docker_node_rm.yaml
index 99a72eb49..a8976c678 100644
--- a/docs/yaml/gen-before/docker_node_rm.yaml
+++ b/docs/yaml/gen-after/docker_node_rm.yaml
@@ -8,7 +8,7 @@ long: |-
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker node rm [OPTIONS] NODE [NODE...]
 pname: docker node
diff --git a/docs/yaml/gen-before/docker_node_update.yaml b/docs/yaml/gen-after/docker_node_update.yaml
index 0cd0a5b7e..1397cc39d 100644
--- a/docs/yaml/gen-before/docker_node_update.yaml
+++ b/docs/yaml/gen-after/docker_node_update.yaml
@@ -7,7 +7,7 @@ long: |-
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker node update [OPTIONS] NODE
 pname: docker node
@@ -77,7 +77,7 @@ examples: |-
   [dockerd](dockerd.md).
 
   For more information about labels, refer to [apply custom
-  metadata](https://docs.docker.com/engine/userguide/labels-custom-metadata/).
+  metadata](/engine/userguide/labels-custom-metadata/).
 deprecated: false
 min_api_version: "1.24"
 experimental: false
diff --git a/docs/yaml/gen-before/docker_plugin_create.yaml b/docs/yaml/gen-after/docker_plugin_create.yaml
index c97419cc3..a5124d414 100644
--- a/docs/yaml/gen-before/docker_plugin_create.yaml
+++ b/docs/yaml/gen-after/docker_plugin_create.yaml
@@ -1,6 +1,6 @@
 command: docker plugin create
-short: Create a plugin from a rootfs and configuration. Plugin data directory must
-  contain config.json and rootfs directory.
+short: |
+  Create a plugin from a rootfs and configuration. Plugin data directory must contain config.json and rootfs directory.
 long: |-
   Creates a plugin. Before creating the plugin, prepare the plugin's root filesystem as well as
   [the config.json](../../extend/config.md)
diff --git a/docs/yaml/gen-before/docker_plugin_inspect.yaml b/docs/yaml/gen-after/docker_plugin_inspect.yaml
index ed5542732..87edde8ee 100644
--- a/docs/yaml/gen-before/docker_plugin_inspect.yaml
+++ b/docs/yaml/gen-after/docker_plugin_inspect.yaml
@@ -66,7 +66,7 @@ examples: |-
     "Manifest": {
       "ManifestVersion": "v0",
       "Description": "A test plugin for Docker",
-      "Documentation": "https://docs.docker.com/engine/extend/plugins/",
+      "Documentation": "/engine/extend/plugins/",
       "Interface": {
         "Types": [
           "docker.volumedriver/1.0"
diff --git a/docs/yaml/gen-before/docker_ps.yaml b/docs/yaml/gen-after/docker_ps.yaml
index 48f912a5b..6d8981d9d 100644
--- a/docs/yaml/gen-before/docker_ps.yaml
+++ b/docs/yaml/gen-after/docker_ps.yaml
@@ -121,7 +121,7 @@ examples: |-
     * The "size" information shows the amount of data (on disk) that is used for the _writable_ layer of each container
     * The "virtual size" is the total amount of disk-space used for the read-only _image_ data used by the container and the writable layer.
 
-  For more information, refer to the [container size on disk](https://docs.docker.com/storage/storagedriver/#container-size-on-disk) section.
+  For more information, refer to the [container size on disk](/storage/storagedriver/#container-size-on-disk) section.
 
 
   ### Filtering
diff --git a/docs/yaml/gen-before/docker_pull.yaml b/docs/yaml/gen-after/docker_pull.yaml
index 83ddef1c1..a7ab88f5a 100644
--- a/docs/yaml/gen-before/docker_pull.yaml
+++ b/docs/yaml/gen-after/docker_pull.yaml
@@ -16,7 +16,7 @@ long: |-
   before open a connect to registry, you may need to configure the Docker
   daemon's proxy settings, using the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`
   environment variables. To set these environment variables on a host using
-  `systemd`, refer to the [control and configure Docker with systemd](https://docs.docker.com/config/daemon/systemd/#httphttps-proxy)
+  `systemd`, refer to the [control and configure Docker with systemd](/config/daemon/systemd/#httphttps-proxy)
   for variables configuration.
 
   ### Concurrent downloads
@@ -122,7 +122,7 @@ examples: |-
   space.
 
   For more information about images, layers, and the content-addressable store,
-  refer to [understand images, containers, and storage drivers](https://docs.docker.com/storage/storagedriver/).
+  refer to [understand images, containers, and storage drivers](/storage/storagedriver/).
 
 
   ### Pull an image by digest (immutable identifier)
diff --git a/docs/yaml/gen-before/docker_run.yaml b/docs/yaml/gen-after/docker_run.yaml
index 1d2b5986c..2af865f6e 100644
--- a/docs/yaml/gen-before/docker_run.yaml
+++ b/docs/yaml/gen-after/docker_run.yaml
@@ -11,7 +11,7 @@ long: |-
   The `docker run` command can be used in combination with `docker commit` to
   [*change the command that a container runs*](commit.md). There is additional detailed information about `docker run` in the [Docker run reference](../run.md).
 
-  For information on connecting a container to a network, see the ["*Docker network overview*"](https://docs.docker.com/network/).
+  For information on connecting a container to a network, see the ["*Docker network overview*"](/network/).
 usage: docker run [OPTIONS] IMAGE [COMMAND] [ARG...]
 pname: docker
 plink: docker.yaml
@@ -400,8 +400,7 @@ options:
 - option: health-timeout
   value_type: duration
   default_value: 0s
-  description: |
-    Maximum time to allow one check to run (ms|s|m|h) (default 0s)
+  description: Maximum time to allow one check to run (ms|s|m|h) (default 0s)
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -449,8 +448,7 @@ options:
 - option: io-maxbandwidth
   value_type: bytes
   default_value: "0"
-  description: |
-    Maximum IO bandwidth limit for the system drive (Windows only)
+  description: Maximum IO bandwidth limit for the system drive (Windows only)
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -1048,7 +1046,7 @@ examples: |-

 
   By bind-mounting the docker unix socket and statically linked docker
-  binary (refer to [get the linux binary](https://docs.docker.com/engine/install/binaries/#install-static-binaries)),
+  binary (refer to [get the linux binary](/engine/install/binaries/#install-static-binaries)),
   you give the container the full access to create and manipulate the host's
   Docker daemon.
 
@@ -1076,7 +1074,7 @@ examples: |-
   docker run -v c:\foo:c:\existing-directory-with-contents ...

 
-  For in-depth information about volumes, refer to [manage data in containers](https://docs.docker.com/storage/volumes/)
+  For in-depth information about volumes, refer to [manage data in containers](/storage/volumes/)
 
 
   ### Add bind mounts or volumes using the --mount flag
@@ -1109,13 +1107,13 @@ examples: |-
 
   This binds port `8080` of the container to TCP port `80` on `127.0.0.1` of the host
   machine. You can also specify `udp` and `sctp` ports.
-  The [Docker User Guide](https://docs.docker.com/network/links/)
+  The [Docker User Guide](/network/links/)
   explains in detail how to manipulate ports in Docker.
 
   Note that ports which are not bound to the host (i.e., `-p 80:80` instead of
   `-p 127.0.0.1:80:80`) will be accessible from the outside. This also applies if
   you configured UFW to block this specific port, as Docker manages his
-  own iptables rules. [Read more](https://docs.docker.com/network/iptables/)
+  own iptables rules. [Read more](/network/iptables/)
 
bash
   $ docker run --expose 80 ubuntu bash
@@ -1214,7 +1212,7 @@ examples: |-
   You can load multiple label-files by supplying multiple  `--label-file` flags.
 
   For additional information on working with labels, see [*Labels - custom
-  metadata in Docker*](https://docs.docker.com/config/labels-custom-metadata/) in
+  metadata in Docker*](/config/labels-custom-metadata/) in
   the Docker User Guide.
 
   ### Connect a container to a network (--network)
@@ -1380,7 +1378,7 @@ examples: |-
 
   The `--gpus` flag allows you to access NVIDIA GPU resources. First you need to
   install [nvidia-container-runtime](https://nvidia.github.io/nvidia-container-runtime/).
-  Visit [Specify a container's resources](https://docs.docker.com/config/containers/resource_constraints/)
+  Visit [Specify a container's resources](/config/containers/resource_constraints/)
   for more information.
 
   To use `--gpus`, specify which GPUs (or all) to use. If no value is provied, all
diff --git a/docs/yaml/gen-before/docker_secret_create.yaml b/docs/yaml/gen-after/docker_secret_create.yaml
index b5f7b4f29..fcf7c15cf 100644
--- a/docs/yaml/gen-before/docker_secret_create.yaml
+++ b/docs/yaml/gen-after/docker_secret_create.yaml
@@ -3,13 +3,13 @@ short: Create a secret from a file or STDIN as content
 long: |-
   Creates a secret using standard input or from a file for the secret content.
 
-  For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](https://docs.docker.com/engine/swarm/secrets/).
+  For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](/engine/swarm/secrets/).
 
   > **Note**
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker secret create [OPTIONS] SECRET [file|-]
 pname: docker secret
diff --git a/docs/yaml/gen-before/docker_secret_inspect.yaml b/docs/yaml/gen-after/docker_secret_inspect.yaml
index 9fe872c0f..3f9175429 100644
--- a/docs/yaml/gen-before/docker_secret_inspect.yaml
+++ b/docs/yaml/gen-after/docker_secret_inspect.yaml
@@ -9,13 +9,13 @@ long: |-
   Go's [text/template](http://golang.org/pkg/text/template/) package
   describes all the details of the format.
 
-  For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](https://docs.docker.com/engine/swarm/secrets/).
+  For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](/engine/swarm/secrets/).
 
   > **Note**
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker secret inspect [OPTIONS] SECRET [SECRET...]
 pname: docker secret
diff --git a/docs/yaml/gen-before/docker_secret_ls.yaml b/docs/yaml/gen-after/docker_secret_ls.yaml
index e9e1ef8bc..0bdbbd32d 100644
--- a/docs/yaml/gen-before/docker_secret_ls.yaml
+++ b/docs/yaml/gen-after/docker_secret_ls.yaml
@@ -4,13 +4,13 @@ short: List secrets
 long: |-
   Run this command on a manager node to list the secrets in the swarm.
 
-  For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](https://docs.docker.com/engine/swarm/secrets/).
+  For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](/engine/swarm/secrets/).
 
   > **Note**
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker secret ls [OPTIONS]
 pname: docker secret
diff --git a/docs/yaml/gen-before/docker_secret_rm.yaml b/docs/yaml/gen-after/docker_secret_rm.yaml
index 34ee8978d..158cd0db7 100644
--- a/docs/yaml/gen-before/docker_secret_rm.yaml
+++ b/docs/yaml/gen-after/docker_secret_rm.yaml
@@ -4,13 +4,13 @@ short: Remove one or more secrets
 long: |-
   Removes the specified secrets from the swarm.
 
-  For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](https://docs.docker.com/engine/swarm/secrets/).
+  For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](/engine/swarm/secrets/).
 
   > **Note**
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker secret rm SECRET [SECRET...]
 pname: docker secret
diff --git a/docs/yaml/gen-before/docker_service.yaml b/docs/yaml/gen-after/docker_service.yaml
index 8a3e62ccd..912ac684b 100644
--- a/docs/yaml/gen-before/docker_service.yaml
+++ b/docs/yaml/gen-after/docker_service.yaml
@@ -7,7 +7,7 @@ long: |-
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker service
 pname: docker
diff --git a/docs/yaml/gen-before/docker_service_create.yaml b/docs/yaml/gen-after/docker_service_create.yaml
index 8c3a46e72..4da00df5c 100644
--- a/docs/yaml/gen-before/docker_service_create.yaml
+++ b/docs/yaml/gen-after/docker_service_create.yaml
@@ -7,7 +7,7 @@ long: |-
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker service create [OPTIONS] IMAGE [COMMAND] [ARG...]
 pname: docker service
@@ -69,8 +69,7 @@ options:
   shorthand: d
   value_type: bool
   default_value: "false"
-  description: |
-    Exit immediately instead of waiting for the service to converge
+  description: Exit immediately instead of waiting for the service to converge
   deprecated: false
   min_api_version: "1.29"
   experimental: false
@@ -305,8 +304,7 @@ options:
 - option: mode
   value_type: string
   default_value: replicated
-  description: |
-    Service mode (replicated, global, replicated-job, or global-job)
+  description: Service mode (replicated, global, replicated-job, or global-job)
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -475,8 +473,7 @@ options:
   swarm: false
 - option: rollback-failure-action
   value_type: string
-  description: |
-    Action on rollback failure ("pause"|"continue") (default "pause")
+  description: Action on rollback failure ("pause"|"continue") (default "pause")
   deprecated: false
   min_api_version: "1.28"
   experimental: false
@@ -506,8 +503,7 @@ options:
   swarm: false
 - option: rollback-order
   value_type: string
-  description: |
-    Rollback order ("start-first"|"stop-first") (default "stop-first")
+  description: Rollback order ("start-first"|"stop-first") (default "stop-first")
   deprecated: false
   min_api_version: "1.29"
   experimental: false
@@ -623,8 +619,7 @@ options:
   swarm: false
 - option: update-order
   value_type: string
-  description: |
-    Update order ("start-first"|"stop-first") (default "stop-first")
+  description: Update order ("start-first"|"stop-first") (default "stop-first")
   deprecated: false
   min_api_version: "1.29"
   experimental: false
@@ -818,7 +813,7 @@ examples: |-
   When you run a [service update](service_update.md), the scheduler updates a
   maximum of 2 tasks at a time, with `10s` between updates. For more information,
   refer to the [rolling updates
-  tutorial](https://docs.docker.com/engine/swarm/swarm-tutorial/rolling-update/).
+  tutorial](/engine/swarm/swarm-tutorial/rolling-update/).
 
   ### Set environment variables (-e, --env)
 
@@ -867,7 +862,7 @@ examples: |-

 
   For more information about labels, refer to [apply custom
-  metadata](https://docs.docker.com/config/labels-custom-metadata/).
+  metadata](/config/labels-custom-metadata/).
 
   ### Add bind mounts, volumes or memory filesystems
 
@@ -905,7 +900,7 @@ examples: |-
   update the named volume.
 
   For more information about named volumes, see
-  [Data Volumes](https://docs.docker.com/storage/volumes/).
+  [Data Volumes](/storage/volumes/).
 
   The following table describes options which apply to both bind mounts and named
   volumes in a service:
@@ -922,7 +917,7 @@ examples: |-
       <td>
         <p>The type of mount, can be either <tt>volume</tt>, <tt>bind</tt>, <tt>tmpfs</tt>, or <tt>npipe</tt>. Defaults to <tt>volume</tt> if no type is specified.</p>
         <ul>
-          <li><tt>volume</tt>: mounts a <a href="https://docs.docker.com/engine/reference/commandline/volume_create/">managed volume</a>
+          <li><tt>volume</tt>: mounts a <a href="/engine/reference/commandline/volume_create/">managed volume</a>
           into the container.</li> <li><tt>bind</tt>:
           bind-mounts a directory or file from the host into the container.</li>
           <li><tt>tmpfs</tt>: mount a tmpfs in the container</li>
@@ -1083,7 +1078,7 @@ examples: |-
         creation. For example,
         <tt>volume-label=mylabel=hello-world,my-other-label=hello-mars</tt>. For more
         information about labels, refer to
-        <a href="https://docs.docker.com/config/labels-custom-metadata/">apply custom metadata</a>.
+        <a href="/config/labels-custom-metadata/">apply custom metadata</a>.
       </td>
     </tr>
     <tr>
@@ -1491,7 +1486,7 @@ examples: |-
   The swarm extends my-network to each node running the service.
 
   Containers on the same network can access each other using
-  [service discovery](https://docs.docker.com/network/overlay/#container-discovery).
+  [service discovery](/network/overlay/#container-discovery).
 
   Long form syntax of `--network` allows to specify list of aliases and driver options:
   `--network name=my-network,alias=web1,driver-opt=field1=value1`
@@ -1565,7 +1560,7 @@ examples: |-
   the port is only bound on nodes where the service is running, and a given port
   on a node can only be bound once. You can only set the publication mode using
   the long syntax. For more information refer to
-  [Use swarm mode routing mesh](https://docs.docker.com/engine/swarm/ingress/).
+  [Use swarm mode routing mesh](/engine/swarm/ingress/).
 
   ### Provide credential specs for managed service accounts (Windows only)
 
diff --git a/docs/yaml/gen-before/docker_service_inspect.yaml b/docs/yaml/gen-after/docker_service_inspect.yaml
index 6e77d2e6f..c30d1b91e 100644
--- a/docs/yaml/gen-before/docker_service_inspect.yaml
+++ b/docs/yaml/gen-after/docker_service_inspect.yaml
@@ -13,7 +13,7 @@ long: |-
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker service inspect [OPTIONS] SERVICE [SERVICE...]
 pname: docker service
diff --git a/docs/yaml/gen-before/docker_service_logs.yaml b/docs/yaml/gen-after/docker_service_logs.yaml
index 29cd8214a..957d49b45 100644
--- a/docs/yaml/gen-before/docker_service_logs.yaml
+++ b/docs/yaml/gen-after/docker_service_logs.yaml
@@ -7,7 +7,7 @@ long: |-
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 
   The `docker service logs` command can be used with either the name or ID of a
@@ -21,7 +21,7 @@ long: |-
   > the `json-file` or `journald` logging driver.
 
   For more information about selecting and configuring logging drivers, refer to
-  [Configure logging drivers](https://docs.docker.com/config/containers/logging/configure/).
+  [Configure logging drivers](/config/containers/logging/configure/).
 
   The `docker service logs --follow` command will continue streaming the new output from
   the service's `STDOUT` and `STDERR`.
diff --git a/docs/yaml/gen-before/docker_service_ls.yaml b/docs/yaml/gen-after/docker_service_ls.yaml
index f1ecdadc1..cffc42ad8 100644
--- a/docs/yaml/gen-before/docker_service_ls.yaml
+++ b/docs/yaml/gen-after/docker_service_ls.yaml
@@ -8,7 +8,7 @@ long: |-
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker service ls [OPTIONS]
 pname: docker service
diff --git a/docs/yaml/gen-before/docker_service_ps.yaml b/docs/yaml/gen-after/docker_service_ps.yaml
index 3c77d1f97..64405c1eb 100644
--- a/docs/yaml/gen-before/docker_service_ps.yaml
+++ b/docs/yaml/gen-after/docker_service_ps.yaml
@@ -7,7 +7,7 @@ long: |-
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker service ps [OPTIONS] SERVICE [SERVICE...]
 pname: docker service
diff --git a/docs/yaml/gen-before/docker_service_rm.yaml b/docs/yaml/gen-after/docker_service_rm.yaml
index 02a5fc111..8b586489c 100644
--- a/docs/yaml/gen-before/docker_service_rm.yaml
+++ b/docs/yaml/gen-after/docker_service_rm.yaml
@@ -8,7 +8,7 @@ long: |-
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker service rm SERVICE [SERVICE...]
 pname: docker service
diff --git a/docs/yaml/gen-before/docker_service_rollback.yaml b/docs/yaml/gen-after/docker_service_rollback.yaml
index b0581554e..79e4899d3 100644
--- a/docs/yaml/gen-before/docker_service_rollback.yaml
+++ b/docs/yaml/gen-after/docker_service_rollback.yaml
@@ -7,7 +7,7 @@ long: |-
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker service rollback [OPTIONS] SERVICE
 pname: docker service
@@ -17,8 +17,7 @@ options:
   shorthand: d
   value_type: bool
   default_value: "false"
-  description: |
-    Exit immediately instead of waiting for the service to converge
+  description: Exit immediately instead of waiting for the service to converge
   deprecated: false
   min_api_version: "1.29"
   experimental: false
diff --git a/docs/yaml/gen-before/docker_service_scale.yaml b/docs/yaml/gen-after/docker_service_scale.yaml
index f38572231..4c9c02612 100644
--- a/docs/yaml/gen-before/docker_service_scale.yaml
+++ b/docs/yaml/gen-after/docker_service_scale.yaml
@@ -11,7 +11,7 @@ long: |-
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker service scale SERVICE=REPLICAS [SERVICE=REPLICAS...]
 pname: docker service
@@ -21,8 +21,7 @@ options:
   shorthand: d
   value_type: bool
   default_value: "false"
-  description: |
-    Exit immediately instead of waiting for the service to converge
+  description: Exit immediately instead of waiting for the service to converge
   deprecated: false
   min_api_version: "1.29"
   experimental: false
diff --git a/docs/yaml/gen-before/docker_service_update.yaml b/docs/yaml/gen-after/docker_service_update.yaml
index a7a45b38c..932270d8e 100644
--- a/docs/yaml/gen-before/docker_service_update.yaml
+++ b/docs/yaml/gen-after/docker_service_update.yaml
@@ -15,7 +15,7 @@ long: |-
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker service update [OPTIONS] SERVICE
 pname: docker service
@@ -110,8 +110,7 @@ options:
   shorthand: d
   value_type: bool
   default_value: "false"
-  description: |
-    Exit immediately instead of waiting for the service to converge
+  description: Exit immediately instead of waiting for the service to converge
   deprecated: false
   min_api_version: "1.29"
   experimental: false
@@ -686,8 +685,7 @@ options:
   swarm: false
 - option: stop-grace-period
   value_type: duration
-  description: |
-    Time to wait before force killing a container (ns|us|ms|s|m|h)
+  description: Time to wait before force killing a container (ns|us|ms|s|m|h)
   deprecated: false
   experimental: false
   experimentalcli: false
diff --git a/docs/yaml/gen-before/docker_stack_deploy.yaml b/docs/yaml/gen-after/docker_stack_deploy.yaml
index 7db53bb5f..8ba0bd7aa 100644
--- a/docs/yaml/gen-before/docker_stack_deploy.yaml
+++ b/docs/yaml/gen-after/docker_stack_deploy.yaml
@@ -8,7 +8,7 @@ long: |-
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker stack deploy [OPTIONS] STACK
 pname: docker stack
diff --git a/docs/yaml/gen-before/docker_stack_ls.yaml b/docs/yaml/gen-after/docker_stack_ls.yaml
index 50d22c23b..3f049bb62 100644
--- a/docs/yaml/gen-before/docker_stack_ls.yaml
+++ b/docs/yaml/gen-after/docker_stack_ls.yaml
@@ -8,7 +8,7 @@ long: |-
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker stack ls [OPTIONS]
 pname: docker stack
diff --git a/docs/yaml/gen-before/docker_stack_ps.yaml b/docs/yaml/gen-after/docker_stack_ps.yaml
index c04a79fd5..0eae059af 100644
--- a/docs/yaml/gen-before/docker_stack_ps.yaml
+++ b/docs/yaml/gen-after/docker_stack_ps.yaml
@@ -7,7 +7,7 @@ long: |-
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker stack ps [OPTIONS] STACK
 pname: docker stack
diff --git a/docs/yaml/gen-before/docker_stack_rm.yaml b/docs/yaml/gen-after/docker_stack_rm.yaml
index 5355ea86d..dc5560266 100644
--- a/docs/yaml/gen-before/docker_stack_rm.yaml
+++ b/docs/yaml/gen-after/docker_stack_rm.yaml
@@ -8,7 +8,7 @@ long: |-
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker stack rm [OPTIONS] STACK [STACK...]
 pname: docker stack
diff --git a/docs/yaml/gen-before/docker_stack_services.yaml b/docs/yaml/gen-after/docker_stack_services.yaml
index c34f83e94..02e94683e 100644
--- a/docs/yaml/gen-before/docker_stack_services.yaml
+++ b/docs/yaml/gen-after/docker_stack_services.yaml
@@ -7,7 +7,7 @@ long: |-
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker stack services [OPTIONS] STACK
 pname: docker stack
diff --git a/docs/yaml/gen-before/docker_swarm_ca.yaml b/docs/yaml/gen-after/docker_swarm_ca.yaml
index c786822a3..6fa346f58 100644
--- a/docs/yaml/gen-before/docker_swarm_ca.yaml
+++ b/docs/yaml/gen-after/docker_swarm_ca.yaml
@@ -7,7 +7,7 @@ long: |-
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker swarm ca [OPTIONS]
 pname: docker swarm
@@ -24,8 +24,7 @@ options:
   swarm: false
 - option: ca-key
   value_type: pem-file
-  description: |
-    Path to the PEM-formatted root CA key to use for the new cluster
+  description: Path to the PEM-formatted root CA key to use for the new cluster
   deprecated: false
   experimental: false
   experimentalcli: false
diff --git a/docs/yaml/gen-before/docker_swarm_join-token.yaml b/docs/yaml/gen-after/docker_swarm_join-token.yaml
index 323435e3e..5104026e9 100644
--- a/docs/yaml/gen-before/docker_swarm_join-token.yaml
+++ b/docs/yaml/gen-after/docker_swarm_join-token.yaml
@@ -11,7 +11,7 @@ long: |-
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker swarm join-token [OPTIONS] (worker|manager)
 pname: docker swarm
diff --git a/docs/yaml/gen-before/docker_swarm_unlock-key.yaml b/docs/yaml/gen-after/docker_swarm_unlock-key.yaml
index 3ee51295f..9ee7c300c 100644
--- a/docs/yaml/gen-before/docker_swarm_unlock-key.yaml
+++ b/docs/yaml/gen-after/docker_swarm_unlock-key.yaml
@@ -12,7 +12,7 @@ long: |-
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker swarm unlock-key [OPTIONS]
 pname: docker swarm
diff --git a/docs/yaml/gen-before/docker_swarm_unlock.yaml b/docs/yaml/gen-after/docker_swarm_unlock.yaml
index c0334c392..ac9a1adfb 100644
--- a/docs/yaml/gen-before/docker_swarm_unlock.yaml
+++ b/docs/yaml/gen-after/docker_swarm_unlock.yaml
@@ -10,7 +10,7 @@ long: |-
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker swarm unlock
 pname: docker swarm
diff --git a/docs/yaml/gen-before/docker_swarm_update.yaml b/docs/yaml/gen-after/docker_swarm_update.yaml
index 28b6d72ee..d85dcd2da 100644
--- a/docs/yaml/gen-before/docker_swarm_update.yaml
+++ b/docs/yaml/gen-after/docker_swarm_update.yaml
@@ -7,7 +7,7 @@ long: |-
   >
   > This is a cluster management command, and must be executed on a swarm
   > manager node. To learn about managers and workers, refer to the
-  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
+  > [Swarm mode section](/engine/swarm/) in the
   > documentation.
 usage: docker swarm update [OPTIONS]
 pname: docker swarm
diff --git a/docs/yaml/gen-after/docker_system_dial-stdio.yaml b/docs/yaml/gen-after/docker_system_dial-stdio.yaml
new file mode 100644
index 000000000..383df4cb1
--- /dev/null
+++ b/docs/yaml/gen-after/docker_system_dial-stdio.yaml
@@ -0,0 +1,14 @@
+command: docker system dial-stdio
+short: |
+  Proxy the stdio stream to the daemon connection. Should not be invoked manually.
+long: |
+  Proxy the stdio stream to the daemon connection. Should not be invoked manually.
+usage: docker system dial-stdio
+pname: docker system
+plink: docker_system.yaml
+deprecated: false
+experimental: false
+experimentalcli: false
+kubernetes: false
+swarm: false
+
diff --git a/docs/yaml/gen-before/docker_tag.yaml b/docs/yaml/gen-after/docker_tag.yaml
index 0ee4da089..49ba6b5ed 100644
--- a/docs/yaml/gen-before/docker_tag.yaml
+++ b/docs/yaml/gen-after/docker_tag.yaml
@@ -15,7 +15,7 @@ long: |-
   period or a dash and may contain a maximum of 128 characters.
 
   You can group your images together using names and tags, and then upload them
-  to [*Share images on Docker Hub*](https://docs.docker.com/get-started/part3/).
+  to [*Share images on Docker Hub*](/get-started/part3/).
 usage: docker tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]
 pname: docker
 plink: docker.yaml
diff --git a/docs/yaml/gen-before/docker_volume_prune.yaml b/docs/yaml/gen-after/docker_volume_prune.yaml
index 1b1eabc85..82dd58ca3 100644
--- a/docs/yaml/gen-before/docker_volume_prune.yaml
+++ b/docs/yaml/gen-after/docker_volume_prune.yaml
@@ -1,7 +1,7 @@
 command: docker volume prune
 short: Remove all unused local volumes
-long: Remove all unused local volumes. Unused local volumes are those which are not
-  referenced by any containers
+long: |
+  Remove all unused local volumes. Unused local volumes are those which are not referenced by any containers
 usage: docker volume prune [OPTIONS]
 pname: docker volume
 plink: docker_volume.yaml
diff --git a/docs/yaml/gen-before/docker_volume_rm.yaml b/docs/yaml/gen-after/docker_volume_rm.yaml
index 2955ef71e..d4e7124bb 100644
--- a/docs/yaml/gen-before/docker_volume_rm.yaml
+++ b/docs/yaml/gen-after/docker_volume_rm.yaml
@@ -1,7 +1,8 @@
 command: docker volume rm
 aliases: remove
 short: Remove one or more volumes
-long: Remove one or more volumes. You cannot remove a volume that is in use by a container.
+long: |
+  Remove one or more volumes. You cannot remove a volume that is in use by a container.
 usage: docker volume rm [OPTIONS] VOLUME [VOLUME...]
 pname: docker volume
 plink: docker_volume.yaml

silvin-lubecki · 2021-07-15T13:56:44Z

+	cliDoc := cmdDoc{
+		Name:       cmd.CommandPath(),
+		Aliases:    strings.Join(cmd.Aliases, ", "),
+		Short:      forceMultiLine(cmd.Short, 73 /* = 80 - 'short: ' */),


totally nit: could we extract those constants in a const block?

I considered that, thought it would be more complicate to describe that const ("what is short: ?" "what is long:?" (they're the literal length of those strings in the yaml). So while it's a bit ugly, I thought it made more sense to describe it here inline.

added some consts

silvin-lubecki · 2021-07-15T14:07:26Z

 			ValueType:    flag.Value.Type(),
-			DefaultValue: forceMultiLine(flag.DefValue),
-			Description:  forceMultiLine(flag.Usage),
+			DefaultValue: forceMultiLine(flag.DefValue, 64 /* = 80 - '  default_value: ' */),


nit: extract those constants in a const block

added some consts

silvin-lubecki

LGTM

- make sure the target directory is created if missing - add support for custom ID's in headings through `<a>` tags (e.g. `<a name=heading2></a>`). This allows use of custom anchors that work both on GitHub (GFM doesn't support extended MarkDown), and in Jekyll (which does). - add code to cleanup markdown for use in our docs: - remove absolute URLs to https://docs.docker.com - remove tabs in MarkDown, and convert them to 4 spaces. This prevents the YAML conversion from switching between "short" and "long" syntax. Tabs in code examples also don't always work well, so using spaces doesn't hurt for that. - refactor some code for readability, and to be less "hacky" (still lots to be improved though) Signed-off-by: Sebastiaan van Stijn <[email protected]>

Signed-off-by: Sebastiaan van Stijn <[email protected]>

thaJeztah · 2021-07-30T19:28:07Z

Merged this one; @crazy-max is working on extracting this code into a separate repository / module, so that all cli (and cli-plugin) repositories can use that module (without having to keep a copy of the code)

thaJeztah added kind/docs status/2-code-review labels Mar 31, 2021

thaJeztah force-pushed the yamldocs_updates branch from 0c20e19 to 15ef876 Compare March 31, 2021 23:23

thaJeztah force-pushed the yamldocs_updates branch from 15ef876 to 4d2827c Compare July 9, 2021 08:06

silvin-lubecki reviewed Jul 15, 2021

View reviewed changes

Comment thread docs/yaml/yaml.go Outdated

silvin-lubecki reviewed Jul 15, 2021

View reviewed changes

silvin-lubecki approved these changes Jul 15, 2021

View reviewed changes

thaJeztah added 2 commits July 30, 2021 20:43

docs/yaml: add TODO for conditionally skipping root command

b86f513

Signed-off-by: Sebastiaan van Stijn <[email protected]>

thaJeztah force-pushed the yamldocs_updates branch from dfe73e5 to b86f513 Compare July 30, 2021 18:51

thaJeztah merged commit 7cf5cd6 into docker:master Jul 30, 2021

thaJeztah deleted the yamldocs_updates branch July 30, 2021 19:26

thaJeztah added this to the 21.xx milestone Jul 30, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

yamldocs: various improvements#3034

yamldocs: various improvements#3034
thaJeztah merged 2 commits intodocker:masterfrom
thaJeztah:yamldocs_updates

thaJeztah commented Mar 31, 2021 •

edited

Loading

Uh oh!

thaJeztah commented May 25, 2021

Uh oh!

codecov-commenter commented Jul 9, 2021 •

edited

Loading

Uh oh!

thaJeztah commented Jul 13, 2021

Uh oh!

silvin-lubecki Jul 15, 2021

Uh oh!

thaJeztah Jul 15, 2021

Uh oh!

thaJeztah Jul 30, 2021

Uh oh!

Uh oh!

silvin-lubecki Jul 15, 2021

Uh oh!

thaJeztah Jul 30, 2021

Uh oh!

silvin-lubecki left a comment

Uh oh!

thaJeztah commented Jul 30, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

thaJeztah commented Mar 31, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thaJeztah commented May 25, 2021

Uh oh!

codecov-commenter commented Jul 9, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

thaJeztah commented Jul 13, 2021

Uh oh!

silvin-lubecki Jul 15, 2021

Choose a reason for hiding this comment

Uh oh!

thaJeztah Jul 15, 2021

Choose a reason for hiding this comment

Uh oh!

thaJeztah Jul 30, 2021

Choose a reason for hiding this comment

Uh oh!

Uh oh!

silvin-lubecki Jul 15, 2021

Choose a reason for hiding this comment

Uh oh!

thaJeztah Jul 30, 2021

Choose a reason for hiding this comment

Uh oh!

silvin-lubecki left a comment

Choose a reason for hiding this comment

Uh oh!

thaJeztah commented Jul 30, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

thaJeztah commented Mar 31, 2021 •

edited

Loading

codecov-commenter commented Jul 9, 2021 •

edited

Loading