d4rkstar opened a new issue, #44:
URL: https://github.com/apache/openserverless/issues/44
Hello Team. I would like to discuss this proposal.
Actually the cli show the help embedded in go code.
To begin a docops pratice in OpenServerless, it was decided to add markdown
for each cli tool command in the "tool" directory. Another script, from the
openserverless-site repository will catch these files from the repo and use
them to autogenerate the website documentation.
**THE GOAL**: keep the website doc and the cli help aligned. So when the cli
is changed a new site build will update the doc automatically.
So i suggest to make some changes to the CLI:
1. use the standard go embed fs to catch all the markdown files inside the
tool directory.
2. ensure that each markdown file must be named exactly like the tool it
documents (ex. datefmt tool will have datefmt.md file). We need to change the
ToolList to choose which command has markdown help.
3. the markdown help will be fully printed by the ops cli when invoked with
the -h (or --help) flag or when the command doesn't support -h flag but an
invalid number of arguments are passed in (example tool remove).
4. add tests and bats tests for all modifications to cli and tools.
The markdown help file will always have this structure:
````markdown
synopsys (short description of the tool)
```text
Usage:
ops -<toolname> ...
```
## Options
```text
command options here
```
## Examples (optional)
optional examples here
````
Incidentally i wrote some code that implement the described features. The
code is in my fork in these two commits:
- [Changes to the
CLI](https://github.com/apache/openserverless-cli/commit/a1116016735040bd8fc326a0393fa080589543e1)
- [Markdown
docs](https://github.com/apache/openserverless-cli/commit/ab012774b422eaea1427bdbb7cc8bfd754be7b6d)
This code is working, but not completed. Here the missing things (all easy
to implement):
- complete the modifications to each tools to display the markdown help
- do the required changes to bats tests
Let me know if this can be done and i'll submit a PR.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscr...@openserverless.apache.org.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
