Documentation plays a major role in any project. Even if the project is small or too big, the creator or the team behind the project needs to curate the documentation very well such that it'll be useful for new end users to refer and learn to use the project, troubleshoot the problems occurred and lot more. Thus, we, Layer5 have curated the documentation for Meshery to meet such purposes. Not to mention, mesheryctl, the CLI client of Meshery needs a curated documentation as well. This blog describes about the evolution of mesheryctl command reference page.
Initial Command Reference Design
The initial design of mesheryctl command reference page is all made using pure markdown and the functionality is handled using Jekyll, the main framework used for Meshery Docs. This handled great at initial stage but had many limitations, such as:
- Updation of YAML for data is often required
- Design was obselete at initial stage
- No separate pages for each command and subcommand
mesheryctl reference page was desperately needed.
Updated Command Reference Design
To tackle the shortcomings of the previous design, I was tasked to redesign the mesheryctl command reference page entirely. This was a big task at first glance to me, as I was a new contributor back then. Eventually after manipulating the reference section with help of great folks, I was able to pull off the task and the design was updated.
The redesign work was done with help of HTML in markdown and with optimization in YAML code. A sample is given below.
1<!-- Copy this template to create individual doc pages for each mesheryctl commands -->23 <!-- Name of the command -->4 # mesheryctl mesh56 <!-- Description of the command. Preferably a paragraph -->7 ## Description89 {% assign name = site.data.mesheryctlcommands.cmds[page.command] %}10 {{ name.description }}1112 <!-- Basic usage of the command -->13 <pre class="codeblock-pre">14 <div class="codeblock">15 mesheryctl mesh [flags]16 </div>17 </pre>18 ...........
Adding auto generation feature in reference
As time passed, we realized that the command reference missed something for a while, though the design has been changed. Then, we thought the idea of automating the generation of docs such that developers don't need to change the code in docs section while working towards mesheryctl. That's where we got to know that Cobra library (the library for CLI apps made using golang) has a feature to make doc pages automatically. So we decided to incorporate that feature into mesheryctl docs page as well! After making several changes and a PR, I was finally able to introduce the feature in the docs site!
1var startCmd = &cobra.Command {2 Use: "start",3 Short: "Start Meshery",4 Long: `Start Meshery and each of its service mesh components.`,5 Args: cobra.NoArgs,6 Example: `7// Start meshery8mesheryctl system start9// To create a new context for in-cluster Kubernetes deployments and set the new context as your current-context10mesheryctl system context create k8s -p kubernetes -s11// (optional) skip checking for new updates available in Meshery.12mesheryctl system start --skip-update13// Reset Meshery's configuration file to default settings.14mesheryctl system start --reset15// Silently create Meshery's configuration file with default settings16mesheryctl system start --yes17.....18}19 `,
Using this information provided above in each golang file, the markdown page is generated using Cobra CLI library and thus reducing the workload on the developer by automating via GitHub Actions.
This is so far on how the mesheryctl command reference is evolved for now. And I hope that it'll continue to evolve in the field of documentation to serve the users to use Meshery in best way possible.
