Merge pull request #1004 from kpumuk/grammar

Backporting changes to the documentation committed directly to kamal-site

bin/docs

@@ -30,6 +30,7 @@ DOCS = {
   "ssh" => "SSH",
   "sshkit" => "SSHKit"
 }
+DOCS_PATH = "lib/kamal/configuration/docs"
 
 class DocWriter
   attr_reader :from_file, :to_file, :key, :heading, :body, :output, :in_yaml
@@ -70,13 +71,15 @@ class DocWriter
             generate_line(line, heading: place == :new_section)
             place = :in_section
           else
+            output.puts
             output.puts "```yaml"
             output.puts line
             place = :in_yaml
           end
         when :in_yaml, :in_empty_line_yaml
           if line =~ /^ *#/
             output.puts "```"
+            output.puts
             generate_line(line, heading: place == :in_empty_line_yaml)
             place = :in_section
           elsif line.empty?
@@ -92,11 +95,12 @@ class DocWriter
 
     def generate_header
       output.puts "---"
+      output.puts "# This file has been generated from the Kamal source, do not edit directly."
+      output.puts "# Find the source of this file at #{DOCS_PATH}/#{key}.yml in the Kamal repository."
       output.puts "title: #{heading[2..-1]}"
       output.puts "---"
       output.puts
       output.puts heading
-      output.puts
     end
 
     def generate_line(line, heading: false)
@@ -118,18 +122,20 @@ class DocWriter
     end
 
     def linkify(text)
-      text.downcase.gsub(" ", "-")
+      if text == "Configuration overview"
+        "overview"
+      else
+        text.downcase.gsub(" ", "-")
+      end
     end
 
     def titlify(text)
       text.capitalize.gsub("-", " ")
     end
 end
 
-from_dir = File.join(File.dirname(__FILE__), "../lib/kamal/configuration/docs")
+from_dir = File.join(File.dirname(__FILE__), "../#{DOCS_PATH}")
 to_dir = File.join(kamal_site_repo, "docs/configuration")
 Dir.glob("#{from_dir}/*") do |from_file|
-  key = File.basename(from_file, ".yml")
-
   DocWriter.new(from_file, to_dir).write
 end

lib/kamal/configuration/docs/accessory.yml

@@ -3,32 +3,32 @@
 # Accessories can be booted on a single host, a list of hosts, or on specific roles.
 # The hosts do not need to be defined in the Kamal servers configuration.
 #
-# Accessories are managed separately from the main service - they are not updated
-# when you deploy and they do not have zero-downtime deployments.
+# Accessories are managed separately from the main service — they are not updated
+# when you deploy, and they do not have zero-downtime deployments.
 #
 # Run `kamal accessory boot <accessory>` to boot an accessory.
 # See `kamal accessory --help` for more information.
 
 # Configuring accessories
 #
-# First define the accessory in the `accessories`
+# First, define the accessory in the `accessories`:
 accessories:
   mysql:
 
     # Service name
     #
-    # This is used in the service label and defaults to `<service>-<accessory>`
-    # where `<service>` is the main service name from the root configuration
+    # This is used in the service label and defaults to `<service>-<accessory>`,
+    # where `<service>` is the main service name from the root configuration:
     service: mysql
 
     # Image
     #
-    # The Docker image to use, prefix with a registry if not using Docker hub
+    # The Docker image to use, prefix it with a registry if not using Docker Hub:
     image: mysql:8.0
 
     # Accessory hosts
     #
-    # Specify one  of `host`, `hosts` or `roles`
+    # Specify one of `host`, `hosts`, or `roles`:
     host: mysql-db1
     hosts:
       - mysql-db1
@@ -38,12 +38,12 @@ accessories:
 
     # Custom command
     #
-    # You can set a custom command to run in the container, if you do not want to use the default
+    # You can set a custom command to run in the container if you do not want to use the default:
     cmd: "bin/mysqld"
 
     # Port mappings
     #
-    # See https://docs.docker.com/network/, especially note the warning about the security
+    # See https://docs.docker.com/network/, and especially note the warning about the security
     # implications of exposing ports publicly.
     port: "127.0.0.1:3306:3306"
 
@@ -52,20 +52,22 @@ accessories:
       app: myapp
 
     # Options
-    # These are passed to the Docker run command in the form `--<name> <value>`
+    #
+    # These are passed to the Docker run command in the form `--<name> <value>`:
     options:
       restart: always
       cpus: 2
 
     # Environment variables
-    # See kamal docs env for more information
+    #
+    # See kamal docs env for more information:
     env:
       ...
 
     # Copying files
     #
     # You can specify files to mount into the container.
-    # The format is `local:remote` where `local` is the path to the file on the local machine
+    # The format is `local:remote`, where `local` is the path to the file on the local machine
     # and `remote` is the path to the file in the container.
     #
     # They will be uploaded from the local repo to the host and then mounted.
@@ -78,13 +80,13 @@ accessories:
     # Directories
     #
     # You can specify directories to mount into the container. They will be created on the host
-    # before being mounted
+    # before being mounted:
     directories:
       - mysql-logs:/var/log/mysql
 
     # Volumes
     #
     # Any other volumes to mount, in addition to the files and directories.
-    # They are not created or copied before mounting
+    # They are not created or copied before mounting:
     volumes:
       - /path/to/mysql-logs:/var/log/mysql

lib/kamal/configuration/docs/alias.yml

@@ -12,15 +12,15 @@
 aliases:
   console: app exec -r console -i "rails console"
 # You can now open the console with:
+#
 # ```shell
 # kamal console
 # ```
 
 # Configuring aliases
 #
-# Aliases are defined in the root config under the alias key
+# Aliases are defined in the root config under the alias key.
 #
-# Each alias is named and can only contain lowercase letters, numbers, dashes and underscores.
-
+# Each alias is named and can only contain lowercase letters, numbers, dashes, and underscores:
 aliases:
   uname: app exec -p -q -r web "uname -a"

lib/kamal/configuration/docs/boot.yml

@@ -2,18 +2,18 @@
 #
 # When deploying to large numbers of hosts, you might prefer not to restart your services on every host at the same time.
 #
-# Kamal’s default is to boot new containers on all hosts in parallel. But you can control this with the boot configuration.
+# Kamal’s default is to boot new containers on all hosts in parallel. However, you can control this with the boot configuration.
 
 # Fixed group sizes
 #
-# Here we boot 2 hosts at a time with a 10 second gap between each group.
+# Here, we boot 2 hosts at a time with a 10-second gap between each group:
 boot:
   limit: 2
   wait: 10
 
 # Percentage of hosts
 #
-# Here we boot 25% of the hosts at a time with a 2 second gap between each group.
+# Here, we boot 25% of the hosts at a time with a 2-second gap between each group:
 boot:
   limit: 25%
   wait: 2

lib/kamal/configuration/docs/builder.yml

@@ -1,8 +1,8 @@
 # Builder
 #
-# The builder configuration controls how the application is built with `docker build`
+# The builder configuration controls how the application is built with `docker build`.
 #
-# See https://kamal-deploy.org/docs/configuration/builder-examples/ for more information
+# See https://kamal-deploy.org/docs/configuration/builder-examples/ for more information.
 
 # Builder options
 #
@@ -11,15 +11,15 @@ builder:
 
   # Arch
   #
-  # The architectures to build for - you can set an array or just a single value.
+  # The architectures to build for — you can set an array or just a single value.
   #
-  # Allowed values are `amd64` and `arm64`
+  # Allowed values are `amd64` and `arm64`:
   arch:
     - amd64
 
   # Remote
   #
-  # The connection string for a remote builder. If supplied Kamal will use this
+  # The connection string for a remote builder. If supplied, Kamal will use this
   # for builds that do not match the local architecture of the deployment host.
   remote: ssh://docker@docker-builder
 
@@ -28,40 +28,40 @@ builder:
   # If set to false, Kamal will always use the remote builder even when building
   # the local architecture.
   #
-  # Defaults to true
+  # Defaults to true:
   local: true
 
   # Builder cache
   #
-  # The type must be either 'gha' or 'registry'
+  # The type must be either 'gha' or 'registry'.
   #
-  # The image is only used for registry cache. Not compatible with the docker driver
+  # The image is only used for registry cache and is not compatible with the Docker driver:
   cache:
     type: registry
     options: mode=max
     image: kamal-app-build-cache
 
   # Build context
   #
-  # If this is not set, then a local git clone of the repo is used.
+  # If this is not set, then a local Git clone of the repo is used.
   # This ensures a clean build with no uncommitted changes.
   #
-  # To use the local checkout instead you can set the context to `.`, or a path to another directory.
+  # To use the local checkout instead, you can set the context to `.`, or a path to another directory.
   context: .
 
   # Dockerfile
   #
-  # The Dockerfile to use for building, defaults to `Dockerfile`
+  # The Dockerfile to use for building, defaults to `Dockerfile`:
   dockerfile: Dockerfile.production
 
   # Build target
   #
-  # If not set, then the default target is used
+  # If not set, then the default target is used:
   target: production
 
-  # Build Arguments
+  # Build arguments
   #
-  # Any additional build arguments, passed to `docker build` with `--build-arg <key>=<value>`
+  # Any additional build arguments, passed to `docker build` with `--build-arg <key>=<value>`:
   args:
     ENVIRONMENT: production
 
@@ -74,33 +74,31 @@ builder:
 
   # Build secrets
   #
-  # Values are read from .kamal/secrets.
-  #
+  # Values are read from `.kamal/secrets`:
   secrets:
     - SECRET1
     - SECRET2
 
-  # Referencing Build Secrets
+  # Referencing build secrets
   #
   # ```shell
   # # Copy Gemfiles
   # COPY Gemfile Gemfile.lock ./
   #
   # # Install dependencies, including private repositories via access token
-  # # Then remove bundle cache with exposed GITHUB_TOKEN)
+  # # Then remove bundle cache with exposed GITHUB_TOKEN
   # RUN --mount=type=secret,id=GITHUB_TOKEN \
   #   BUNDLE_GITHUB__COM=x-access-token:$(cat /run/secrets/GITHUB_TOKEN) \
   #   bundle install && \
   #   rm -rf /usr/local/bundle/cache
   # ```
 
-
   # SSH
   #
-  # SSH agent socket or keys to expose to the build
+  # SSH agent socket or keys to expose to the build:
   ssh: default=$SSH_AUTH_SOCK
 
   # Driver
   #
-  # The build driver to use, defaults to `docker-container`
+  # The build driver to use, defaults to `docker-container`:
   driver: docker