vtorc cobra docs

Makefile

@@ -41,10 +41,14 @@ check-internal-links: clean build link-checker-setup run-link-checker
 check-all-links: clean build link-checker-setup
 	bin/htmltest --conf .htmltest.external.yml
 
-ifndef VTCTLDCLIENT_VERSION_PAIRS
-export VTCTLDCLIENT_VERSION_PAIRS="main:16.0,v15.0.2:15.0"
+ifndef COBRADOC_VERSION_PAIRS
+export COBRADOC_VERSION_PAIRS="main:16.0,v15.0.2:15.0"
 endif
 
 # Usage: VITESS_DIR=/full/path/to/vitess.io/vitess make vtctldclient-docs
 vtctldclient-docs:
-	go run ./tools/vtctldclientdocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${VTCTLDCLIENT_VERSION_PAIRS}"
+	go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" vtctldclient
+
+# Usage: VITESS_DIR=/full/path/to/vitess.io/vitess make vtorc-docs
+vtorc-docs:
+	go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" vtorc

content/en/docs/18.0/reference/programs/vtorc/_index.md

@@ -0,0 +1,105 @@
+---
+title: vtorc
+series: vtorc
+---
+## vtorc
+
+
+
+```
+vtorc [flags]
+```
+
+### Options
+
+```
+      --allow-emergency-reparent                                    Whether VTOrc should be allowed to run emergency reparent operation when it detects a dead primary (default true)
+      --alsologtostderr                                             log to standard error as well as files
+      --audit-file-location string                                  File location where the audit logs are to be stored
+      --audit-purge-duration duration                               Duration for which audit logs are held before being purged. Should be in multiples of days (default 168h0m0s)
+      --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
+      --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.
+      --config-file-not-found-handling ConfigFileNotFoundHandling   Behavior when a config file is not found. (Options: error, exit, ignore, warn) (default warn)
+      --config-name string                                          Name of the config file (without extension) to search for. (default "vtconfig")
+      --config-path strings                                         Paths to search for config files in. (default [/Users/andrew/dev/vitess])
+      --config-persistence-min-interval duration                    minimum interval between persisting dynamic config changes back to disk (if no change has occurred, nothing is done). (default 1s)
+      --config-type string                                          Config file type (omit to infer config type from file extension).
+      --consul_auth_static_file string                              JSON File to read the topos/tokens from.
+      --emit_stats                                                  If set, emit stats to push-based monitoring and stats backends
+      --grpc_auth_static_client_creds string                        When using grpc_static_auth in the server, this file provides the credentials to use to authenticate with server.
+      --grpc_compression string                                     Which protocol to use for compressing gRPC. Default: nothing. Supported: snappy
+      --grpc_enable_tracing                                         Enable gRPC tracing.
+      --grpc_initial_conn_window_size int                           gRPC initial connection window size
+      --grpc_initial_window_size int                                gRPC initial window size
+      --grpc_keepalive_time duration                                After a duration of this time, if the client doesn't see any activity, it pings the server to see if the transport is still alive. (default 10s)
+      --grpc_keepalive_timeout duration                             After having pinged for keepalive check, the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default 10s)
+      --grpc_max_message_size int                                   Maximum allowed RPC message size. Larger messages will be rejected by gRPC with the error 'exceeding the max size'. (default 16777216)
+      --grpc_prometheus                                             Enable gRPC monitoring with Prometheus.
+  -h, --help                                                        help for vtorc
+      --instance-poll-time duration                                 Timer duration on which VTOrc refreshes MySQL information (default 5s)
+      --keep_logs duration                                          keep logs for this long (using ctime) (zero to keep forever)
+      --keep_logs_by_mtime duration                                 keep logs for this long (using mtime) (zero to keep forever)
+      --lameduck-period duration                                    keep running at least this long after SIGTERM before stopping (default 50ms)
+      --lock-timeout duration                                       Maximum time for which a shard/keyspace lock can be acquired for (default 45s)
+      --log_dir string                                              If non-empty, write log files in this directory
+      --log_err_stacks                                              log stack traces for errors
+      --log_rotate_max_size uint                                    size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800)
+      --logtostderr                                                 log to standard error instead of files
+      --max-stack-size int                                          configure the maximum stack size in bytes (default 67108864)
+      --onclose_timeout duration                                    wait no more than this for OnClose handlers before stopping (default 10s)
+      --onterm_timeout duration                                     wait no more than this for OnTermSync handlers before stopping (default 10s)
+      --pid_file string                                             If set, the process will write its pid to the named file, and delete it on graceful shutdown.
+      --port int                                                    port for the server
+      --pprof strings                                               enable profiling
+      --prevent-cross-cell-failover                                 Prevent VTOrc from promoting a primary in a different cell than the current primary in case of a failover
+      --purge_logs_interval duration                                how often try to remove old logs (default 1h0m0s)
+      --reasonable-replication-lag duration                         Maximum replication lag on replicas which is deemed to be acceptable (default 10s)
+      --recovery-period-block-duration duration                     Duration for which a new recovery is blocked on an instance after running a recovery (default 30s)
+      --recovery-poll-duration duration                             Timer duration on which VTOrc polls its database to run a recovery (default 1s)
+      --remote_operation_timeout duration                           time to wait for a remote operation (default 15s)
+      --security_policy string                                      the name of a registered security policy to use for controlling access to URLs - empty means allow all for anyone (built-in policies: deny-all, read-only)
+      --shutdown_wait_time duration                                 Maximum time to wait for VTOrc to release all the locks that it is holding before shutting down on SIGTERM (default 30s)
+      --snapshot-topology-interval duration                         Timer duration on which VTOrc takes a snapshot of the current MySQL information it has in the database. Should be in multiple of hours
+      --sqlite-data-file string                                     SQLite Datafile to use as VTOrc's database (default "file::memory:?mode=memory&cache=shared")
+      --stats_backend string                                        The name of the registered push-based monitoring/stats backend to use
+      --stats_combine_dimensions string                             List of dimensions to be combined into a single "all" value in exported stats vars
+      --stats_common_tags strings                                   Comma-separated list of common tags for the stats backend. It provides both label and values. Example: label1:value1,label2:value2
+      --stats_drop_variables string                                 Variables to be dropped from the list of exported variables.
+      --stats_emit_period duration                                  Interval between emitting stats to all registered backends (default 1m0s)
+      --stderrthreshold severity                                    logs at or above this threshold go to stderr (default 1)
+      --table-refresh-interval int                                  interval in milliseconds to refresh tables in status page with refreshRequired class
+      --tablet_manager_grpc_ca string                               the server ca to use to validate servers when connecting
+      --tablet_manager_grpc_cert string                             the cert to use to connect
+      --tablet_manager_grpc_concurrency int                         concurrency to use to talk to a vttablet server for performance-sensitive RPCs (like ExecuteFetchAs{Dba,AllPrivs,App}) (default 8)
+      --tablet_manager_grpc_connpool_size int                       number of tablets to keep tmclient connections open to (default 100)
+      --tablet_manager_grpc_crl string                              the server crl to use to validate server certificates when connecting
+      --tablet_manager_grpc_key string                              the key to use to connect
+      --tablet_manager_grpc_server_name string                      the server name to use to validate server certificate
+      --tablet_manager_protocol string                              Protocol to use to make tabletmanager RPCs to vttablets. (default "grpc")
+      --topo-information-refresh-duration duration                  Timer duration on which VTOrc refreshes the keyspace and vttablet records from the topology server (default 15s)
+      --topo_consul_lock_delay duration                             LockDelay for consul session. (default 15s)
+      --topo_consul_lock_session_checks string                      List of checks for consul session. (default "serfHealth")
+      --topo_consul_lock_session_ttl string                         TTL for consul session.
+      --topo_consul_watch_poll_duration duration                    time of the long poll for watch queries. (default 30s)
+      --topo_etcd_lease_ttl int                                     Lease TTL for locks and leader election. The client will use KeepAlive to keep the lease going. (default 30)
+      --topo_etcd_tls_ca string                                     path to the ca to use to validate the server cert when connecting to the etcd topo server
+      --topo_etcd_tls_cert string                                   path to the client cert to use to connect to the etcd topo server, requires topo_etcd_tls_key, enables TLS
+      --topo_etcd_tls_key string                                    path to the client key to use to connect to the etcd topo server, enables TLS
+      --topo_global_root string                                     the path of the global topology data in the global topology server
+      --topo_global_server_address string                           the address of the global topology server
+      --topo_implementation string                                  the topology implementation to use
+      --topo_zk_auth_file string                                    auth to use when connecting to the zk topo server, file contents should be <scheme>:<auth>, e.g., digest:user:pass
+      --topo_zk_base_timeout duration                               zk base timeout (see zk.Connect) (default 30s)
+      --topo_zk_max_concurrency int                                 maximum number of pending requests to send to a Zookeeper server. (default 64)
+      --topo_zk_tls_ca string                                       the server ca to use to validate servers when connecting to the zk topo server
+      --topo_zk_tls_cert string                                     the cert to use to connect to the zk topo server, requires topo_zk_tls_key, enables TLS
+      --topo_zk_tls_key string                                      the key to use to connect to the zk topo server, enables TLS
+      --v Level                                                     log level for V logs
+  -v, --version                                                     print binary version
+      --wait-replicas-timeout duration                              Duration for which to wait for replica's to respond when issuing RPCs (default 30s)
+```
+

tools/vtctldclientdocs/main.go → tools/cobradocs/main.go

@@ -26,11 +26,13 @@ import (
 )
 
 var (
-	usage       = "Generates website documentation for the `vtctldclient` binary for a given set of <vitessio/vitess-gitref>:<vitessio/website-version> pairs."
+	usage       = "Generates website documentation for the given binary for a given set of <vitessio/vitess-gitref>:<vitessio/website-version> pairs."
 	debug       = flag.Bool("debug", false, "log debug info")
 	vitessDir   = flag.String("vitess-dir", "", "path to vitess checkout")
-	docGenPath  = flag.String("vtctldclientdocgen-path", "./go/cmd/vtctldclient/docgen", "path to the vtctldclient doc generator, **relative to** --vitess-dir")
-	versionStrs = flag.String("version-pairs", "main:16.0", "CSV of <gitref>:<version> pairs to generate docs for; for example, 'v15.0.2:15.0' will generate docs from the v15.0.2 tag into the content/en/15.0 subtree. ensure your vitess checkout is up-to-date (git fetch --all) before running.")
+	docGenPath  = flag.String("docgen-path", "", "path to the binary docs generator, **relative to** --vitess-dir. if blank, defaults to ./go/cmd/`binary`/docgen")
+	versionStrs = flag.String("version-pairs", "main:17.0", "CSV of <gitref>:<version> pairs to generate docs for; for example, 'v15.0.2:15.0' will generate docs from the v15.0.2 tag into the content/en/15.0 subtree. ensure your vitess checkout is up-to-date (git fetch --all) before running.")
+
+	binaryName string
 )
 
 func getValidWorkdir() (string, error) {
@@ -70,11 +72,17 @@ func unwrap[T any](t T, err error) T {
 func main() {
 	flag.Usage = func() {
 		fmt.Fprintf(flag.CommandLine.Output(), "Usage of %s:\n", os.Args[0])
+		fmt.Fprintf(flag.CommandLine.Output(), "%s <binary>\n", os.Args[0])
 		fmt.Fprintf(flag.CommandLine.Output(), "\n%s\n\n", usage)
 		flag.PrintDefaults()
 	}
 	flag.Parse()
 
+	binaryName = flag.Arg(0)
+	if binaryName == "" {
+		log.Fatalf("binary name is required")
+	}
+
 	wd := unwrap(getValidWorkdir())
 
 	if *vitessDir == "" {
@@ -103,6 +111,10 @@ func main() {
 		versions = append(versions, version)
 	}
 
+	if *docGenPath == "" {
+		*docGenPath = fmt.Sprintf("./go/cmd/%s/docgen", binaryName)
+	}
+
 	for _, version := range versions {
 		must(version.GenerateDocs(wd, *vitessDir, *docGenPath))
 	}

tools/vtctldclientdocs/version.go → tools/cobradocs/version.go

@@ -29,7 +29,7 @@ type version struct {
 }
 
 func (v version) Dir(root string) string {
-	return filepath.Join(root, "content", "en", "docs", v.DocVersion, "reference", "programs", "vtctldclient")
+	return filepath.Join(root, "content", "en", "docs", v.DocVersion, "reference", "programs", binaryName)
 }
 
 func (v version) GenerateDocs(workdir string, vitessDir string, docgenPath string) (err error) {