Bedrock CLI operation level documentation should be generated from code

[andrebriggs]

As a: Developer

I want: Operation level documentation that is always in async with the implementation. We have markdown in different location in git and there is chances that they are out of async with implementation. I want to have one md file for each command that describe extensively about the command. During code review, reviewers are always responsible for reviewing the content of this md files.

So that: there is one md file that I know that I need to update whenever I made changes to the command. And the command declaration should be automatically generated for me. Hand craft command declaration like this may be out of sync with implementation. In short, I don't have to manually up date the hadn't written Markdown files. Doing this manually can lead to errors and out of date documentation.

Describe the solution you'd like:

One solution is to add a Markdown for every command file. For instance right now each class in a command directory has class.ts, class.test.ts, and class.decorator.json:

.
├── index.ts
├── init.decorator.json
├── init.test.ts
├── init.ts
├── pipeline.decorator.json
├── pipeline.test.ts
├── pipeline.ts
├── reconcile.decorator.json
├── reconcile.test.ts
└── reconcile.ts

A proposal would be to add an additional file name class.md for each command like this

.
├── index.ts
├── init.decorator.json
├── init.md.ts
├── init.test.ts
├── init.ts
├── pipeline.decorator.json
├── pipeline.md.ts
├── pipeline.test.ts
├── pipeline.ts
├── reconcile.decorator.json
├── reconcile.md.ts
├── reconcile.test.ts
└── reconcile.ts

in this new Markdown file, we describe the command (what the command is about, when and how to use it). Once we have these in place, we generate documentation for each command - its descriptions and syntax.

Workflow from @dennisseah:

Acceptance Criteria: each command has a markdown and it describes extensively about what the command is about and when and how to use it

Describe alternatives you've considered:

Additional context:

Does this require updates to documentation?: Yes, a document explaining what we need to do when we create a new command.

1. we need to 4 files, .decorator.json, .md.json, .test.json, .ts
2. code coverage for the command
3. content for .md.json
4. code structure and exit code for .ts

Execution Plan:

• [x] make sure that all pull requests are merged to docs folder
• [x] rename docs folder to documentations
• [x] add static contents to (new) docs folder
• [x] provide the code to consolidate all command declaration json files into one
• [x] add a few md files to show where these md files should be located. rest of the team members need to contribute
• [x] add a liner to package.json "gen-doc": "ts-node tools/generateDoc.ts > docs/data/doc.json" so that it can execute yarn gen-doc when releasing a new release
• [x] Handle multiple release versions of documentation

The structure in workspace and tool to generate docs are provided. There are the reminding things that the team can work on

• [ ] standardize on the content of md. E.g. need a description, sample, option: Additional information
• [x] improve and add missing md files for spk deployment commands
• [x] improve and add missing md files for spk hld commands
• [x] improve and add missing md files for spk infra commands
• [x] improve and add missing md files for spk project commands
• [x] improve and add missing md files for spk service commands
• [ ] improve layout of the web page https://catalystcode.github.io/spk/commands/index.html

[andrebriggs]

Additional ideas are to use Typedoc or Microsoft's TsDoc.

Both utilize comments in code as a way to generate documentation.

cc @dennisseah

[dennisseah]

cmdDocs.pptx animated slide