consolidate docs (#1583)

* regen consolidated docs Signed-off-by: Andrew Mason <andrew@planetscale.com> * remove handwritten vtctld/vtorc docs Signed-off-by: Andrew Mason <andrew@planetscale.com> * no need to manage checkouts if ref is HEAD Signed-off-by: Andrew Mason <andrew@planetscale.com> * add ability to generate all docs with one target Signed-off-by: Andrew Mason <andrew@planetscale.com> * fix sidebar expanders this makes it so we only expand if there are actual "regular pages" (i.e. not just `_index.md`) in a section Signed-off-by: Andrew Mason <andrew@planetscale.com> --------- Signed-off-by: Andrew Mason <andrew@planetscale.com>
vitessio · Sep 14, 2023 · 5e45cc7 · 5e45cc7
1 parent d5f14fd
commit 5e45cc7
Show file tree

Hide file tree

Showing 7 changed files with 58 additions and 300 deletions.
diff --git a/Makefile b/Makefile
@@ -45,6 +45,8 @@ ifndef COBRADOC_VERSION_PAIRS
 export COBRADOC_VERSION_PAIRS="main:16.0,v15.0.2:15.0"
 endif
 
+generated-docs: vtctld-docs vtctldclient-docs vtgate-docs vtorc-docs vttablet-docs
+
 # Usage: VITESS_DIR=/full/path/to/vitess.io/vitess make vtctld-docs
 vtctld-docs:
 	go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" vtctld

diff --git a/content/en/docs/18.0/reference/programs/vtctld.md b/content/en/docs/18.0/reference/programs/vtctld.md
diff --git a/content/en/docs/18.0/reference/programs/vtctld/_index.md b/content/en/docs/18.0/reference/programs/vtctld/_index.md
@@ -6,10 +6,34 @@ series: vtctld
 
 The Vitess cluster management daemon.
 
+### Synopsis
+
+vtctld provides web and gRPC interfaces to manage a single Vitess cluster.
+It is usually the first Vitess component to be started after a valid global topology service has been created.
+
+For the last several releases, vtctld has been transitioning to a newer gRPC service for well-typed cluster management requests.
+This is **required** to use programs such as vtadmin and vtctldclient, and The old API and service are deprecated and will be removed in a future release.
+To enable this newer service, include "grpc-vtctld" in the --service_map argument.
+This is demonstrated in the example usage below.
+
 ```
 vtctld [flags]
 ```
 
+### Examples
+
+```
+vtctld \
+	--topo_implementation etcd2 \
+	--topo_global_server_address localhost:2379 \
+	--topo_global_root /vitess/ \
+	--service_map 'grpc-vtctl,grpc-vtctld' \
+	--backup_storage_implementation file \
+	--file_backup_storage_root $VTDATAROOT/backups \
+	--port 15000 \
+	--grpc_port 15999
+```
+
 ### Options
 
 ```

diff --git a/content/en/docs/18.0/reference/programs/vtorc.md b/content/en/docs/18.0/reference/programs/vtorc.md
diff --git a/content/en/docs/18.0/reference/programs/vtorc/_index.md b/content/en/docs/18.0/reference/programs/vtorc/_index.md
@@ -10,6 +10,21 @@ VTOrc is the automated fault detection and repair tool in Vitess.
 vtorc [flags]
 ```
 
+### Examples
+
+```
+vtorc \
+	--topo_implementation etcd2 \
+	--topo_global_server_address localhost:2379 \
+	--topo_global_root /vitess/global \
+	--log_dir $VTDATAROOT/tmp \
+	--port 15000 \
+	--recovery-period-block-duration "10m" \
+	--instance-poll-time "1s" \
+	--topo-information-refresh-duration "30s" \
+	--alsologtostderr
+```
+
 ### Options
 
 ```
@@ -20,6 +35,7 @@ vtorc [flags]
       --audit-to-backend                                            Whether to store the audit log in the VTOrc database
       --audit-to-syslog                                             Whether to store the audit log in the syslog
       --catch-sigpipe                                               catch and ignore SIGPIPE on stdout and stderr if specified
+      --change-tablets-with-errant-gtid-to-drained                  Whether VTOrc should be changing the type of tablets with errant GTIDs to DRAINED
       --clusters_to_watch strings                                   Comma-separated list of keyspaces or keyspace/shards that this instance will monitor and repair. Defaults to all clusters in the topology. Example: "ks1,ks2/-80"
       --config string                                               config file name
       --config-file string                                          Full path of the config file (with extension) to use. If set, --config-path, --config-type, and --config-name are ignored.

diff --git a/layouts/partials/docs/sidebar.html b/layouts/partials/docs/sidebar.html
@@ -32,6 +32,7 @@
       {{/* 'docs_nav_disable_expand' is (currently only) used to hide the caret on the "Older Version Docs" link */}}
       {{/* We can remove it with a better versioning system: see https://github.com/vitessio/website/issues/625 */}}
       {{ $isExpandable := and .IsSection (not .Params.docs_nav_disable_expand) }}
+      {{ $isExpandable := and $isExpandable (gt (len .RegularPages) 0) }}
       {{ $expandableClass := cond $isExpandable "expandable" "" }}
 
       <li class="{{ $expandedClass }} {{ $activeClass }}">

diff --git a/tools/cobradocs/version.go b/tools/cobradocs/version.go
@@ -47,21 +47,23 @@ func (v version) GenerateDocs(workdir string, vitessDir string, docgenPath strin
 		}
 	}()
 
-	gitCheckout := exec.Command("git", "checkout", v.Ref)
-	debugf(gitCheckout.String())
-	if err = gitCheckout.Run(); err != nil {
-		return err
-	}
-
-	defer func() {
-		gitCheckout := exec.Command("git", "checkout", "-")
+	if v.Ref != "HEAD" {
+		gitCheckout := exec.Command("git", "checkout", v.Ref)
 		debugf(gitCheckout.String())
-		if checkoutErr := gitCheckout.Run(); checkoutErr != nil {
-			if err == nil {
-				err = checkoutErr
-			}
+		if err = gitCheckout.Run(); err != nil {
+			return err
 		}
-	}()
+
+		defer func() {
+			gitCheckout := exec.Command("git", "checkout", "-")
+			debugf(gitCheckout.String())
+			if checkoutErr := gitCheckout.Run(); checkoutErr != nil {
+				if err == nil {
+					err = checkoutErr
+				}
+			}
+		}()
+	}
 
 	if err = isDir(filepath.Join(vitessDir, docgenPath)); err != nil {
 		err = fmt.Errorf("cannot find docgen tool directory: %w", err)