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 ofmesheryctl 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
Thus, the idea for redesigning the mesheryctl reference page was desperately needed.
Updated Command Reference Design
To tackle the shortcomings of the previous design, I was tasked to redesign themesheryctl 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.
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!
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.
