more graceful docgen by ajm188 · Pull Request #1588 · vitessio/website

ajm188 · 2023-09-18T10:31:56Z

skip programs who either don't have a target directory (in content/en/.../) for that version, or don't have a docgen directory (go/cmd//docgen) in vitessio/vitess for that gitref

this allows us to freely bulk-generate docs for all programs/versions without having to get fussy about it

Example Output

(note i have upstream/main checked out as vmain so i tweaked the makefile locally)

Details

``` ➜ vtwebsite git:(andrew/docgen-graceful) ✗ VITESS_DIR=~/dev/vitess make generated-docs go run ./tools/cobradocs/ --vitess-dir "/Users/andrew/dev/vitess" --version-pairs ""vmain:18.0,v17.0.2:17.0,v16.0.4:16.0,v15.0.4:15.0"" vtctld 2023/09/18 06:27:41 [warning] cannot find directory for doc version v17.0.2:17.0 (index=1): stat /Users/andrew/dev/vtwebsite/content/en/docs/17.0/reference/programs/vtctld: no such file or directory 2023/09/18 06:27:41 [warning] cannot find directory for doc version v16.0.4:16.0 (index=2): stat /Users/andrew/dev/vtwebsite/content/en/docs/16.0/reference/programs/vtctld: no such file or directory 2023/09/18 06:27:41 [warning] cannot find directory for doc version v15.0.4:15.0 (index=3): stat /Users/andrew/dev/vtwebsite/content/en/docs/15.0/reference/programs/vtctld: no such file or directory go run ./tools/cobradocs/ --vitess-dir "/Users/andrew/dev/vitess" --version-pairs ""vmain:18.0,v17.0.2:17.0,v16.0.4:16.0,v15.0.4:15.0"" vtctldclient go run ./tools/cobradocs/ --vitess-dir "/Users/andrew/dev/vitess" --version-pairs ""vmain:18.0,v17.0.2:17.0,v16.0.4:16.0,v15.0.4:15.0"" vtgate 2023/09/18 06:28:01 [warning] cannot find directory for doc version v17.0.2:17.0 (index=1): stat /Users/andrew/dev/vtwebsite/content/en/docs/17.0/reference/programs/vtgate: no such file or directory 2023/09/18 06:28:01 [warning] cannot find directory for doc version v16.0.4:16.0 (index=2): stat /Users/andrew/dev/vtwebsite/content/en/docs/16.0/reference/programs/vtgate: no such file or directory 2023/09/18 06:28:01 [warning] cannot find directory for doc version v15.0.4:15.0 (index=3): stat /Users/andrew/dev/vtwebsite/content/en/docs/15.0/reference/programs/vtgate: no such file or directory go run ./tools/cobradocs/ --vitess-dir "/Users/andrew/dev/vitess" --version-pairs ""vmain:18.0,v17.0.2:17.0,v16.0.4:16.0,v15.0.4:15.0"" vtorc 2023/09/18 06:28:04 [warning] cannot find directory for doc version v17.0.2:17.0 (index=1): stat /Users/andrew/dev/vtwebsite/content/en/docs/17.0/reference/programs/vtorc: no such file or directory 2023/09/18 06:28:04 [warning] cannot find directory for doc version v16.0.4:16.0 (index=2): stat /Users/andrew/dev/vtwebsite/content/en/docs/16.0/reference/programs/vtorc: no such file or directory 2023/09/18 06:28:04 [warning] cannot find directory for doc version v15.0.4:15.0 (index=3): stat /Users/andrew/dev/vtwebsite/content/en/docs/15.0/reference/programs/vtorc: no such file or directory go run ./tools/cobradocs/ --vitess-dir "/Users/andrew/dev/vitess" --version-pairs ""vmain:18.0,v17.0.2:17.0,v16.0.4:16.0,v15.0.4:15.0"" vttablet 2023/09/18 06:28:05 [warning] cannot find directory for doc version v17.0.2:17.0 (index=1): stat /Users/andrew/dev/vtwebsite/content/en/docs/17.0/reference/programs/vttablet: no such file or directory 2023/09/18 06:28:05 [warning] cannot find directory for doc version v16.0.4:16.0 (index=2): stat /Users/andrew/dev/vtwebsite/content/en/docs/16.0/reference/programs/vttablet: no such file or directory 2023/09/18 06:28:05 [warning] cannot find directory for doc version v15.0.4:15.0 (index=3): stat /Users/andrew/dev/vtwebsite/content/en/docs/15.0/reference/programs/vttablet: no such file or directory ➜ vtwebsite git:(andrew/docgen-graceful) ✗ echo $? 0 ```

skip programs who either don't have a target directory (in content/en/.../) for that version, or don't have a docgen directory (go/cmd/<binary>/docgen) in vitessio/vitess for that gitref this allows us to freely bulk-generate docs for all programs/versions without having to get fussy about it Signed-off-by: Andrew Mason <andrew@planetscale.com>

netlify · 2023-09-18T10:32:57Z

✅ Deploy Preview for vitess ready!

Name	Link
🔨 Latest commit	`9a30356`
🔍 Latest deploy log	https://app.netlify.com/sites/vitess/deploys/6508271ed7cc5900082705bb
😎 Deploy Preview	https://deploy-preview-1588--vitess.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

deepthi

All my comments are to do with lowercase vs uppercase. I believe they will need to change in the main repo and the docs have to be regenerated.

deepthi · 2023-09-20T14:55:11Z

content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/_index.md

 ### Synopsis

-MoveTables commands: Create, Show, Status, SwitchTraffic, ReverseTraffic, Stop, Start, Cancel, and Delete.
+moveTables commands: Create, Show, Status, SwitchTraffic, ReverseTraffic, Stop, Start, Cancel, and Delete.


Why did the case change on this?

https://github.com/vitessio/vitess/blob/main/go/cmd/vtctldclient/command/vreplication/movetables/movetables.go#L30

deepthi · 2023-09-20T14:55:33Z

content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/_index.md

 * [vtctldclient MoveTables cancel](./vtctldclient_movetables_cancel/)	 - Cancel a MoveTables VReplication workflow.
 * [vtctldclient MoveTables complete](./vtctldclient_movetables_complete/)	 - Complete a MoveTables VReplication workflow.
-* [vtctldclient MoveTables create](./vtctldclient_movetables_create/)	 - Create and optionally run a MoveTables VReplication workflow.
+* [vtctldclient MoveTables create](./vtctldclient_movetables_create/)	 - Create and optionally run a moveTables VReplication workflow.


https://github.com/vitessio/vitess/blob/main/go/cmd/vtctldclient/command/vreplication/movetables/create.go#L47

deepthi · 2023-09-20T14:55:47Z

....0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_create.md

 ## vtctldclient MoveTables create

-Create and optionally run a MoveTables VReplication workflow.
+Create and optionally run a moveTables VReplication workflow.


https://github.com/vitessio/vitess/blob/main/go/cmd/vtctldclient/command/vreplication/movetables/create.go#L47

deepthi · 2023-09-20T14:55:55Z

....0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_create.md

-      --tablet-types-in-preference-order   When performing source tablet selection, look for candidates in the type order as they are listed in the tablet-types flag (default true)
+      --on-ddl string                      What to do when DDL is encountered in the VReplication stream. Possible values are IGNORE, STOP, EXEC, and EXEC_IGNORE. (default "IGNORE")
+      --source-keyspace string             Keyspace where the tables are being moved from (required).
+      --source-shards strings              Source shards to copy data from when performing a partial moveTables (experimental).


deepthi · 2023-09-20T14:56:53Z

content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/_index.md

-* [vtctldclient OnlineDDL cancel](./vtctldclient_onlineddl_cancel/)	 - Cancel one or all pending migrations, terminating any actively running ones.
+* [vtctldclient OnlineDDL cancel](./vtctldclient_onlineddl_cancel/)	 - cancel one or all migrations, terminating any running ones as needed.
 * [vtctldclient OnlineDDL cleanup](./vtctldclient_onlineddl_cleanup/)	 - Mark a given schema migration ready for artifact cleanup.
-* [vtctldclient OnlineDDL complete](./vtctldclient_onlineddl_complete/)	 - Complete one or all migrations executed with `--postpone-completion`.
-* [vtctldclient OnlineDDL launch](./vtctldclient_onlineddl_launch/)	 - Launch one or all migrations executed with `--postpone-launch`.
+* [vtctldclient OnlineDDL complete](./vtctldclient_onlineddl_complete/)	 - complete one or all migrations executed with --postpone-completion
+* [vtctldclient OnlineDDL launch](./vtctldclient_onlineddl_launch/)	 - launch one or all migrations executed with --postpone-launch
 * [vtctldclient OnlineDDL retry](./vtctldclient_onlineddl_retry/)	 - Mark a given schema migration for retry.
 * [vtctldclient OnlineDDL show](./vtctldclient_onlineddl_show/)	 - Display information about online DDL operations.
-* [vtctldclient OnlineDDL throttle](./vtctldclient_onlineddl_throttle/)	 - Throttle one or all migrations.
-* [vtctldclient OnlineDDL unthrottle](./vtctldclient_onlineddl_unthrottle/)	 - Unthrottle one or all migrations.
+* [vtctldclient OnlineDDL throttle](./vtctldclient_onlineddl_throttle/)	 - Throttles one or all migrations
+* [vtctldclient OnlineDDL unthrottle](./vtctldclient_onlineddl_unthrottle/)	 - Unthrottles one or all migrations


Inconsistent casing. Some start with upper, some with lower.

deepthi · 2023-09-20T14:57:09Z

...18.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/vtctldclient_OnlineDDL_cancel.md

 ## vtctldclient OnlineDDL cancel

-Cancel one or all pending migrations, terminating any actively running ones.
+cancel one or all migrations, terminating any running ones as needed.


My preference is Cancel vs. cancel.

deepthi · 2023-09-20T14:57:18Z

....0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/vtctldclient_OnlineDDL_complete.md

 ## vtctldclient OnlineDDL complete

-Complete one or all migrations executed with `--postpone-completion`.
+complete one or all migrations executed with --postpone-completion


Complete.

deepthi · 2023-09-20T14:57:28Z

...18.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/vtctldclient_OnlineDDL_launch.md

 ## vtctldclient OnlineDDL launch

-Launch one or all migrations executed with `--postpone-launch`.
+launch one or all migrations executed with --postpone-launch


ajm188 · 2023-09-20T16:13:18Z

tl;dr all the casing changes were made in the main codebase but never regenerated back to the website docs. this is just correcting that

i’ll defer to @rohit-nayak-ps for what consistency he wants there (i.e. i’d like to get the main change in and follow up for the consistentcy)

ajm188 requested review from GuptaManan100, deepthi and mattlord September 18, 2023 10:31

ajm188 mentioned this pull request Sep 18, 2023

Update VTOrc flags to include --change-tablets-with-errant-gtid-to-drained #1574

Closed

deepthi reviewed Sep 20, 2023

View reviewed changes

deepthi approved these changes Sep 20, 2023

View reviewed changes

deepthi merged commit 0020cea into prod Sep 20, 2023

deepthi deleted the andrew/docgen-graceful branch September 20, 2023 17:36

Conversation

ajm188 commented Sep 18, 2023

Example Output

Uh oh!

netlify bot commented Sep 18, 2023

✅ Deploy Preview for vitess ready!

Uh oh!

deepthi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ajm188 commented Sep 20, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants