CLOUDP-317123 change markup for code blocks in Atlas CLI generated docs #4006

fmenezes · 2025-06-24T14:34:40Z

Proposed changes

change markup for code blocks in Atlas CLI generated docs

Closes #[issue number]

Checklist

I have signed the MongoDB CLA
I have added tests that prove my fix is effective or that my feature works
I have added any necessary documentation in document requirements section listed in CONTRIBUTING.md (if appropriate)
I have addressed the @mongodb/docs-cloud-team comments (if appropriate)
I have updated test/README.md (if an e2e test has been added)
I have run make fmt and formatted my code

Further comments

Ignore commits with "update docs" or "gen docs", these are auto generated text files, feel free to ignore .json or .sh files.

jwilliams-mongo · 2025-06-24T22:16:19Z

tools/cmd/docs/transformations.go

 				}
-				sb.WriteString(".. Code end marker, please don't delete this comment\n\n")
+				sb.WriteString("   :language: shell\n")


this would have to be indented three additional spaces to account for directive syntax change

Suggested change

sb.WriteString(" :language: shell\n")

sb.WriteString(" :language: shell\n")

jwilliams-mongo · 2025-06-24T22:17:50Z

tools/cmd/docs/transformations.go

 				}
+				sb.WriteString(fmt.Sprintf("   literalinclude:: /includes/%s\n", includePayloadFileName))


tweak to adhere to restructured text directive syntax

Suggested change

sb.WriteString(fmt.Sprintf(" literalinclude:: /includes/%s\n", includePayloadFileName))

sb.WriteString(fmt.Sprintf(" .. literalinclude:: /includes/%s\n", includePayloadFileName))

jwilliams-mongo · 2025-06-24T22:18:08Z

tools/cmd/docs/transformations.go

-				sb.WriteString(" --" + flagName + " " + ex.Flags[flagName])
-			}
-			sb.WriteString("\n\n")
+			sb.WriteString(fmt.Sprintf("literalinclude:: /includes/%s\n", includeCommandFileName))


same as above

Suggested change

sb.WriteString(fmt.Sprintf("literalinclude:: /includes/%s\n", includeCommandFileName))

sb.WriteString(fmt.Sprintf(".. literalinclude:: /includes/%s\n", includeCommandFileName))

jwilliams-mongo · 2025-06-24T22:18:36Z

tools/cmd/docs/transformations.go

 			if tabs {
 				sb.WriteString("      ")
 			}
-			sb.WriteString(".. Code end marker, please don't delete this comment\n\n")
+			sb.WriteString(":language: shell\n")


same as above

Suggested change

sb.WriteString(":language: shell\n")

sb.WriteString(" :language: shell\n")

fmenezes · 2025-06-25T16:46:30Z

@jwilliams-mongo do you want to double check again?

jwilliams-mongo · 2025-06-25T18:26:56Z

tools/cmd/docs/main.go

@@ -25,13 +25,18 @@ import (
 	"github.com/spf13/cobra"
 )

+const (
+	docsPath     = "./docs/command"
+	includesPath = "./docs/command/includes"


Suggested change

includesPath = "./docs/command/includes"

includesPath = "./docs/includes"

the includes are being nested within the command directory. For docs-mongodb-internal, the command directory is not within includes, so the docs build is not able to find the files. For cloud-docs, the includes are nested too deeply and the build is not able to find them without updating the paths to be more specific.

this will make it easier to place the includes in the right folder in the destination repositories as part of a separate workflow and have a single includes path in the commands that can apply to both docs repos.

in addition to this change, I believe we can add new workflows in https://github.com/mongodb/mongodb-atlas-cli/edit/master/build/ci/copy.bara.sky.template to add new destination_files and new transformations.

the new transformation would move the includes into this new subdirectory, called something like includes/atlas-cli-examples

jwilliams-mongo · 2025-06-25T19:19:59Z

tools/cmd/docs/transformations.go

 				}
+				sb.WriteString(fmt.Sprintf("   .. literalinclude:: /includes/%s\n", includePayloadFileName))


we likely need to amend this as well if we add a new workflow that adds a subdirectory for these examples under includes

Suggested change

sb.WriteString(fmt.Sprintf(" .. literalinclude:: /includes/%s\n", includePayloadFileName))

sb.WriteString(fmt.Sprintf(" .. literalinclude:: /includes/atlas-cli-examples/%s\n", includePayloadFileName))

jwilliams-mongo · 2025-06-25T19:20:35Z

tools/cmd/docs/transformations.go

-				sb.WriteString(" --" + flagName + " " + ex.Flags[flagName])
-			}
-			sb.WriteString("\n\n")
+			sb.WriteString(fmt.Sprintf(".. literalinclude:: /includes/%s\n", includeCommandFileName))


Suggested change

sb.WriteString(fmt.Sprintf(".. literalinclude:: /includes/%s\n", includeCommandFileName))

sb.WriteString(fmt.Sprintf(".. literalinclude:: /includes/atlas-cli-examples/%s\n", includeCommandFileName))

fmenezes · 2025-06-26T14:47:59Z

latest copybara tests are https://github.com/10gen/cloud-docs/pull/7371 and https://github.com/10gen/docs-mongodb-internal/pull/12512

jwilliams-mongo

@fmenezes thanks for your efforts here. LGTM!

github-actions · 2025-06-26T14:54:51Z

Coverage Report 📉

Branch	Commit	Coverage
master	`ff05591`	25.8%
CLOUDP-317123	`73fa7aa`	25.7%
	Difference	-.1%

gssbzn

LGTM

fmenezes changed the title ~~CLOUDP 317123~~ CLOUDP-317123 change markup for code blocks in Atlas CLI generated docs Jun 24, 2025

github-actions bot added the atlascli label Jun 24, 2025

fmenezes force-pushed the CLOUDP-317123 branch 5 times, most recently from 21dd5ef to d452809 Compare June 24, 2025 15:18

fmenezes added 2 commits June 24, 2025 16:23

CLOUDP-317123 change markup for code blocks in Atlas CLI generated docs

bc477ab

update docs

d9f30f8

fmenezes force-pushed the CLOUDP-317123 branch 2 times, most recently from 93e6ca4 to d9f30f8 Compare June 24, 2025 17:24

fmenezes marked this pull request as ready for review June 24, 2025 17:24

fmenezes requested review from a team as code owners June 24, 2025 17:24

jwilliams-mongo reviewed Jun 24, 2025

View reviewed changes

fmenezes added 4 commits June 25, 2025 16:51

debug copybara

6209b46

add --force to copybara

f47953b

address comments

0b18f81

update docs

754afeb

jwilliams-mongo reviewed Jun 25, 2025

View reviewed changes

fmenezes added 2 commits June 26, 2025 11:35

address comments

9e37a8a

gen docs

4137e8b

fix copybara slack messages

73fa7aa

fmenezes requested a review from jwilliams-mongo June 26, 2025 14:52

jwilliams-mongo approved these changes Jun 26, 2025

View reviewed changes

gssbzn approved these changes Jun 26, 2025

View reviewed changes

fmenezes merged commit 891d09f into master Jun 26, 2025
22 checks passed

fmenezes deleted the CLOUDP-317123 branch June 26, 2025 15:21

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

CLOUDP-317123 change markup for code blocks in Atlas CLI generated docs #4006

CLOUDP-317123 change markup for code blocks in Atlas CLI generated docs #4006

Uh oh!

fmenezes commented Jun 24, 2025 •

edited

Loading

Uh oh!

jwilliams-mongo Jun 24, 2025

Uh oh!

jwilliams-mongo Jun 24, 2025

Uh oh!

jwilliams-mongo Jun 24, 2025

Uh oh!

jwilliams-mongo Jun 24, 2025

Uh oh!

fmenezes commented Jun 25, 2025

Uh oh!

jwilliams-mongo Jun 25, 2025 •

edited

Loading

Uh oh!

jwilliams-mongo Jun 25, 2025

Uh oh!

jwilliams-mongo Jun 25, 2025

Uh oh!

jwilliams-mongo Jun 25, 2025

Uh oh!

fmenezes commented Jun 26, 2025

Uh oh!

jwilliams-mongo left a comment

Uh oh!

github-actions bot commented Jun 26, 2025

Uh oh!

gssbzn left a comment

Uh oh!

Uh oh!

Uh oh!

	sb.WriteString(" :language: shell\n")
	sb.WriteString(" :language: shell\n")

		}
		sb.WriteString(fmt.Sprintf(" literalinclude:: /includes/%s\n", includePayloadFileName))

	sb.WriteString(fmt.Sprintf(" literalinclude:: /includes/%s\n", includePayloadFileName))
	sb.WriteString(fmt.Sprintf(" .. literalinclude:: /includes/%s\n", includePayloadFileName))

	sb.WriteString(fmt.Sprintf("literalinclude:: /includes/%s\n", includeCommandFileName))
	sb.WriteString(fmt.Sprintf(".. literalinclude:: /includes/%s\n", includeCommandFileName))

	sb.WriteString(":language: shell\n")
	sb.WriteString(" :language: shell\n")

	includesPath = "./docs/command/includes"
	includesPath = "./docs/includes"

CLOUDP-317123 change markup for code blocks in Atlas CLI generated docs #4006

CLOUDP-317123 change markup for code blocks in Atlas CLI generated docs #4006

Uh oh!

Conversation

fmenezes commented Jun 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes

Checklist

Further comments

Uh oh!

jwilliams-mongo Jun 24, 2025

Choose a reason for hiding this comment

Uh oh!

jwilliams-mongo Jun 24, 2025

Choose a reason for hiding this comment

Uh oh!

jwilliams-mongo Jun 24, 2025

Choose a reason for hiding this comment

Uh oh!

jwilliams-mongo Jun 24, 2025

Choose a reason for hiding this comment

Uh oh!

fmenezes commented Jun 25, 2025

Uh oh!

jwilliams-mongo Jun 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jwilliams-mongo Jun 25, 2025

Choose a reason for hiding this comment

Uh oh!

jwilliams-mongo Jun 25, 2025

Choose a reason for hiding this comment

Uh oh!

jwilliams-mongo Jun 25, 2025

Choose a reason for hiding this comment

Uh oh!

fmenezes commented Jun 26, 2025

Uh oh!

jwilliams-mongo left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Jun 26, 2025

Uh oh!

gssbzn left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

fmenezes commented Jun 24, 2025 •

edited

Loading

jwilliams-mongo Jun 25, 2025 •

edited

Loading