fix: Prevent Manually Added Content in CLI Docs to be Overwritten #9125

aboobakersiddiqr63 · 2023-10-16T12:19:14Z

Notes for Reviewers

This PR fixes #9104

Signed commits

[ ✓] Yes, I signed my commits.

Signed-off-by: Aboobaker Siddiq R <aboobakersiddiq63@gmail.com>

codecov · 2023-10-16T12:31:13Z

Codecov Report

Attention: 13 lines in your changes are missing coverage. Please review.

Comparison is base (2949e28) 10.11% compared to head (979747d) 10.18%.
Report is 67 commits behind head on master.

❗ Current head 979747d differs from pull request most recent head b623613. Consider uploading reports for the commit b623613 to get more accurate results

Files	Patch %	Lines
mesheryctl/doc/doc.go	59.37%	10 Missing and 3 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #9125      +/-   ##
==========================================
+ Coverage   10.11%   10.18%   +0.07%     
==========================================
  Files         136      136              
  Lines       21193    21201       +8     
==========================================
+ Hits         2143     2160      +17     
+ Misses      18729    18717      -12     
- Partials      321      324       +3

Flag	Coverage Δ
unittests	`10.18% <59.37%> (+0.07%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

Signed-off-by: Aboobaker Siddiq R <aboobakersiddiq63@gmail.com>

l5io · 2023-10-17T04:32:57Z

🚀 Preview for commit 73d569d at: https://652e0e5a9bb75234d233d311--meshery-docs-preview.netlify.app

Signed-off-by: Aboobaker Siddiq R <aboobakersiddiq63@gmail.com>

l5io · 2023-10-17T04:54:00Z

🚀 Preview for commit 3977467 at: https://652e1350165c1d3b995e5577--meshery-docs-preview.netlify.app

saurabh100ni · 2023-10-17T19:09:49Z

Thanks for raising the PR, let's Discuss this in the Meshery Development Call today,
Please add this as an agenda in the Doc : Doc

Signed-off-by: Aboobaker Siddiq R <aboobakersiddiq63@gmail.com>

l5io · 2023-10-18T11:16:34Z

🚀 Preview for commit d88c6dc at: https://652fbe74e46c95112af055f2--meshery-docs-preview.netlify.app

Signed-off-by: Aboobaker Siddiq R <aboobakersiddiq63@gmail.com>

l5io · 2023-10-18T11:48:12Z

🚀 Preview for commit b43c313 at: https://652fc5e21989fd1b7600dc93--meshery-docs-preview.netlify.app

alphaX86

Great effort. Curious though. So to invoke this user would be applying them on the markdown page or in go program?

aboobakersiddiqr63 · 2023-10-19T18:21:42Z

Great effort. Curious though. So to invoke this user would be applying them on the markdown page or in go program?

Thanks @alphaX86. The user just needs to add the comment on the md file

Signed-off-by: Aboobaker Siddiq R <aboobakersiddiq63@gmail.com>

l5io · 2023-10-21T12:04:26Z

🚀 Preview for commit 997e5eb at: https://6533be2256d42a1ab87ea689--meshery-docs-preview.netlify.app

Signed-off-by: Aboobaker Siddiq R <aboobakersiddiq63@gmail.com>

l5io · 2023-10-21T13:42:00Z

🚀 Preview for commit 1322fda at: https://6533d503e7d324284f546288--meshery-docs-preview.netlify.app

leecalcote · 2023-10-24T04:59:36Z

docs/pages/project/contributing/contributing-cli.md

+## Preserving Manually Added Documentation with Cobra CLI
+
+We use Cobra CLI and GitHub Actions to automate the generation of command documentation. To protect any manually added content and ensure it remains intact after regeneration, follow this format: {% raw %}{% include folder-name/file-name %}{% endraw %}. This format should reference an external file where your manual changes are stored. Any content added using this format will not be altered during the documentation generation process. When making new changes or additions, be sure to place them at the end of the documentation to keep it organized and consistent.
+


Suggested change

## Preserving Manually Added Documentation with Cobra CLI

We use Cobra CLI and GitHub Actions to automate the generation of command documentation. To protect any manually added content and ensure it remains intact after regeneration, follow this format: {% raw %}{% include folder-name/file-name %}{% endraw %}. This format should reference an external file where your manual changes are stored. Any content added using this format will not be altered during the documentation generation process. When making new changes or additions, be sure to place them at the end of the documentation to keep it organized and consistent.

## Preserving Manually Added Documentation

`mesheryctl` uses Cobra CLI and GitHub Actions to automate the generation of command documentation. On occasion, additional documentation beyond that included in the `mesheryctl` Golang files is ideal to capture and include in the CLI reference pages. Contributors are encouraged to add more usage examples, screenshots, video explainers and so forth to any of the CLI reference pages. To protect any manually added content and ensure it remains intact after regeneration, create a separate Jekyll `include` file. Follow file naming scheme outlined below:

{% raw %}{% include mesheryctl/ %}{% endraw %}

This format should reference an external file where your manual changes are stored. Any content added using this method will not be altered during the documentation generation process, but instead will be included post-auto doc generation. When making new changes or additions, understand that these additional details are positioned at the end their given CLI reference page, so bear this in mind as you organize and present your additional command details.

leecalcote · 2023-10-24T05:00:39Z

mesheryctl/doc/doc.go

@@ -206,9 +215,10 @@ func GenMarkdownCustom(cmd *cobra.Command, w io.Writer) error {
 				}
 			})
 		}
-		buf.WriteString("Go back to [command reference index](/reference/mesheryctl/) ")
+		buf.WriteString("Go back to [command reference index](/reference/mesheryctl/), if you want to add content manually to the CLI documentation, please refer to the [instruction](/project/contributing/contributing-cli#preserving-manually-added-documentation-with-cobra-cli) for guidance.")


Suggested change

buf.WriteString("Go back to [command reference index](/reference/mesheryctl/), if you want to add content manually to the CLI documentation, please refer to the [instruction](/project/contributing/contributing-cli#preserving-manually-added-documentation-with-cobra-cli) for guidance.")

buf.WriteString("Go back to [command reference index](/reference/mesheryctl/), if you want to add content manually to the CLI documentation, please refer to the [instruction](/project/contributing/contributing-cli#preserving-manually-added-documentation) for guidance.")

leecalcote

Looking good. 👍

I think this new include method is a bit cleaner. Nice work.

saurabh100ni · 2023-10-24T19:00:42Z

Let's discuss this on the Meshery dev call tomorrow at 7:30 pm IST / 9:00 am CT,
Please add this as your agenda item in Docs: https://docs.google.com/document/d/1Dg4Uz9rGTuGHmYZwIt47z1j5x3LmnpxD1M1SgypAkQ0/edit

leecalcote · 2023-10-26T05:46:46Z

@aboobakersiddiqr63 will you send word when you have added an include file example to the Contributing portion of this PR?

Signed-off-by: Aboobaker Siddiq R <aboobakersiddiq63@gmail.com>

aboobakersiddiqr63 · 2023-10-28T17:48:54Z

@alphaX86

@aboobakersiddiqr63 will you send word when you have added an include file example to the Contributing portion of this PR?

@leecalcote added an example of how to add manual content to the cli docs and updated other changes you have mentioned

I could not find an example actually. Could you share any markdown file utilizing this ability?

@alphaX86 I have added the example to contributing-cli.md file on how to proceed

alphaX86 · 2023-10-29T16:49:22Z

@aboobakersiddiqr63 noted. I'll try this and get back to you then 👍

leecalcote · 2023-11-05T22:04:21Z

Gents, do we have an example for the docs?

Good to merge after this, yes?

abhijeetgauravm · 2023-11-14T16:22:38Z

Hey @aboobakersiddiqr63 Let's discuss this on Meshery Development Meeting tomorrow at 8:30 PM IST / 9 AM Central time. Please add this as an agenda item in the meeting minutes.

MUzairS15 · 2023-11-18T15:42:31Z

@alphaX86 Can you finish this off. // @aboobakersiddiqr63

alphaX86 · 2023-11-19T13:37:43Z

@alphaX86 Can you finish this off. // @aboobakersiddiqr63

I'll wrap this up @MUzairS15

l5io · 2023-11-19T13:43:03Z

🚀 Preview for commit 979747d at: https://655a10c9040c8637e4340e96--meshery-docs-preview.netlify.app

leecalcote · 2023-11-22T05:41:46Z

@alphaX86 Can you finish this off. // @aboobakersiddiqr63

I'll wrap this up @MUzairS15

@alphaX86 good to go?

alphaX86 · 2023-11-22T05:58:40Z

@alphaX86 Can you finish this off. // @aboobakersiddiqr63

I'll wrap this up @MUzairS15

@alphaX86 good to go?

I'm testing the changes @leecalcote. Once they are good, we're good to merge this by EOD.

l5io · 2023-11-22T16:10:54Z

🚀 Preview for commit bfb8611 at: https://655e27ef2a036247e6b1d648--meshery-docs-preview.netlify.app

Signed-off-by: Aadhitya A <aadhitya864@gmail.com>

alphaX86

Tested the changes 🟢. Made changes in doc page as well. LGTM 👍

alphaX86 · 2023-11-22T16:47:53Z

Hold... one bug found in docs. Fixing it quick...

l5io · 2023-11-22T16:59:08Z

🚀 Preview for commit 32a9aa9 at: https://655e333de2e9a44fe798016e--meshery-docs-preview.netlify.app

l5io · 2023-11-22T17:05:53Z

🚀 Preview for commit 13a9e0a at: https://655e34cf2a03625285b1d70e--meshery-docs-preview.netlify.app

l5io · 2023-11-22T17:12:27Z

🚀 Preview for commit 2e37e32 at: https://655e365ce3d8f2562c9cf96e--meshery-docs-preview.netlify.app

Signed-off-by: Aadhitya A <aadhitya864@gmail.com>

l5io · 2023-11-22T17:18:28Z

🚀 Preview for commit b623613 at: https://655e37c4b2a3c44dee74d4fe--meshery-docs-preview.netlify.app

alphaX86 · 2023-11-22T17:20:21Z

Fixed. We're good now // @leecalcote

leecalcote · 2023-11-22T17:55:50Z

Roger, Roger. Thank you, @alphaX86

fix: Prevent Manually Added Content To be Overwritten

6fd171b

Signed-off-by: Aboobaker Siddiq R <aboobakersiddiq63@gmail.com>

github-actions bot added the component/mesheryctl CLI for Meshery label Oct 16, 2023

aboobakersiddiqr63 added 3 commits October 16, 2023 19:20

Added test for the getManuallyAddedContentMap method

26136e8

Signed-off-by: Aboobaker Siddiq R <aboobakersiddiq63@gmail.com>

Minor change in test.doc passed filename directly

ca6353f

Signed-off-by: Aboobaker Siddiq R <aboobakersiddiq63@gmail.com>

Added Documentation Content to Preserve Manually Added Content

73d569d

Signed-off-by: Aboobaker Siddiq R <aboobakersiddiq63@gmail.com>

github-actions bot added the area/docs Documentation update needed label Oct 17, 2023

Added hyperlink to CLI Documentation to Preserver Manually Added Content

3977467

Signed-off-by: Aboobaker Siddiq R <aboobakersiddiq63@gmail.com>

leecalcote requested review from alphaX86 and zakisk October 17, 2023 21:09

minor change

d88c6dc

Signed-off-by: Aboobaker Siddiq R <aboobakersiddiq63@gmail.com>

Empty Commit

b43c313

Signed-off-by: Aboobaker Siddiq R <aboobakersiddiq63@gmail.com>

alphaX86 reviewed Oct 19, 2023

View reviewed changes

Changed the logic to check for {% include}

997e5eb

Signed-off-by: Aboobaker Siddiq R <aboobakersiddiq63@gmail.com>

Added Docs Changes after the logic change

1322fda

Signed-off-by: Aboobaker Siddiq R <aboobakersiddiq63@gmail.com>

leecalcote reviewed Oct 24, 2023

View reviewed changes

leecalcote previously approved these changes Oct 24, 2023

View reviewed changes

leecalcote requested a review from hexxdump October 25, 2023 17:40

Added example oh how to preserve the manually added content

f34721d

Signed-off-by: Aboobaker Siddiq R <aboobakersiddiq63@gmail.com>

Merge branch 'master' into aboobakersiddiqr63/docs-manualcont-changes

979747d

Merge branch 'master' into aboobakersiddiqr63/docs-manualcont-changes

bfb8611

alphaX86 force-pushed the aboobakersiddiqr63/docs-manualcont-changes branch from 58bcf3b to c398859 Compare November 22, 2023 16:20

Edit doc page to reflect the instructions clear

3c38c86

Signed-off-by: Aadhitya A <aadhitya864@gmail.com>

alphaX86 force-pushed the aboobakersiddiqr63/docs-manualcont-changes branch from c398859 to 3c38c86 Compare November 22, 2023 16:22

alphaX86 previously approved these changes Nov 22, 2023

View reviewed changes

alphaX86 dismissed their stale review via 32a9aa9 November 22, 2023 16:55

alphaX86 force-pushed the aboobakersiddiqr63/docs-manualcont-changes branch from 32a9aa9 to 13a9e0a Compare November 22, 2023 17:01

alphaX86 force-pushed the aboobakersiddiqr63/docs-manualcont-changes branch from 13a9e0a to 2e37e32 Compare November 22, 2023 17:08

Fix docs bug

b623613

Signed-off-by: Aadhitya A <aadhitya864@gmail.com>

alphaX86 force-pushed the aboobakersiddiqr63/docs-manualcont-changes branch from 2e37e32 to b623613 Compare November 22, 2023 17:14

alphaX86 approved these changes Nov 22, 2023

View reviewed changes

leecalcote merged commit 4eea7ae into meshery:master Nov 22, 2023
12 of 15 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: Prevent Manually Added Content in CLI Docs to be Overwritten #9125

fix: Prevent Manually Added Content in CLI Docs to be Overwritten #9125

aboobakersiddiqr63 commented Oct 16, 2023

codecov bot commented Oct 16, 2023 •

edited

l5io commented Oct 17, 2023

l5io commented Oct 17, 2023

saurabh100ni commented Oct 17, 2023

l5io commented Oct 18, 2023

l5io commented Oct 18, 2023

alphaX86 left a comment

aboobakersiddiqr63 commented Oct 19, 2023

l5io commented Oct 21, 2023

l5io commented Oct 21, 2023

leecalcote Oct 24, 2023 •

edited

leecalcote Oct 24, 2023

leecalcote left a comment

saurabh100ni commented Oct 24, 2023

leecalcote commented Oct 26, 2023 •

edited

aboobakersiddiqr63 commented Oct 28, 2023

alphaX86 commented Oct 29, 2023

leecalcote commented Nov 5, 2023

abhijeetgauravm commented Nov 14, 2023

MUzairS15 commented Nov 18, 2023

alphaX86 commented Nov 19, 2023

l5io commented Nov 19, 2023

leecalcote commented Nov 22, 2023

alphaX86 commented Nov 22, 2023

l5io commented Nov 22, 2023

alphaX86 left a comment

alphaX86 commented Nov 22, 2023

l5io commented Nov 22, 2023

l5io commented Nov 22, 2023

l5io commented Nov 22, 2023

l5io commented Nov 22, 2023

alphaX86 commented Nov 22, 2023

leecalcote commented Nov 22, 2023

		## Preserving Manually Added Documentation with Cobra CLI

		We use Cobra CLI and GitHub Actions to automate the generation of command documentation. To protect any manually added content and ensure it remains intact after regeneration, follow this format: {% raw %}{% include folder-name/file-name %}{% endraw %}. This format should reference an external file where your manual changes are stored. Any content added using this format will not be altered during the documentation generation process. When making new changes or additions, be sure to place them at the end of the documentation to keep it organized and consistent.

	buf.WriteString("Go back to [command reference index](/reference/mesheryctl/), if you want to add content manually to the CLI documentation, please refer to the [instruction](/project/contributing/contributing-cli#preserving-manually-added-documentation-with-cobra-cli) for guidance.")
	buf.WriteString("Go back to [command reference index](/reference/mesheryctl/), if you want to add content manually to the CLI documentation, please refer to the [instruction](/project/contributing/contributing-cli#preserving-manually-added-documentation) for guidance.")

fix: Prevent Manually Added Content in CLI Docs to be Overwritten #9125

fix: Prevent Manually Added Content in CLI Docs to be Overwritten #9125

Conversation

aboobakersiddiqr63 commented Oct 16, 2023

codecov bot commented Oct 16, 2023 • edited

Codecov Report

l5io commented Oct 17, 2023

l5io commented Oct 17, 2023

saurabh100ni commented Oct 17, 2023

l5io commented Oct 18, 2023

l5io commented Oct 18, 2023

alphaX86 left a comment

Choose a reason for hiding this comment

aboobakersiddiqr63 commented Oct 19, 2023

l5io commented Oct 21, 2023

l5io commented Oct 21, 2023

leecalcote Oct 24, 2023 • edited

Choose a reason for hiding this comment

leecalcote Oct 24, 2023

Choose a reason for hiding this comment

leecalcote left a comment

Choose a reason for hiding this comment

saurabh100ni commented Oct 24, 2023

leecalcote commented Oct 26, 2023 • edited

aboobakersiddiqr63 commented Oct 28, 2023

alphaX86 commented Oct 29, 2023

leecalcote commented Nov 5, 2023

abhijeetgauravm commented Nov 14, 2023

MUzairS15 commented Nov 18, 2023

alphaX86 commented Nov 19, 2023

l5io commented Nov 19, 2023

leecalcote commented Nov 22, 2023

alphaX86 commented Nov 22, 2023

l5io commented Nov 22, 2023

alphaX86 left a comment

Choose a reason for hiding this comment

alphaX86 commented Nov 22, 2023

l5io commented Nov 22, 2023

l5io commented Nov 22, 2023

l5io commented Nov 22, 2023

l5io commented Nov 22, 2023

alphaX86 commented Nov 22, 2023

leecalcote commented Nov 22, 2023

codecov bot commented Oct 16, 2023 •

edited

leecalcote Oct 24, 2023 •

edited

leecalcote commented Oct 26, 2023 •

edited