docs: update usage doc with info about --watch flag and absence of --version flag
#1142
Conversation
To reflect changes in asyncapi generate fromTemplate command for --watch option
eelcofolkertsma
requested review from
Florence-Njeri,
derberg and
asyncapi-bot-eve
as code owners
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Welcome to AsyncAPI. Thanks a lot for creating your first pull request. Please check out our contributors guide useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.
eelcofolkertsma
changed the title
derberg
changed the title
--watch flag and absence of --version flag
derberg
changed the title
--watch flag and absence of --version flag--watch flag and absence of --version flag
|
@Florence-Njeri hey, please have a look and approve |
|
@derberg taking a look |
docs/usage.md
Outdated
| @@ -149,4 +154,4 @@ try { | |||
| } | |||
| ``` | |||
|
|
|||
| See the [API documentation](api) for more examples and full API reference information. | |||
| See the [API documentation](/docs/tools/generator/api) for more examples and full API reference information. | |||
There was a problem hiding this comment.
This leads to a 404 error. We should leave it as is @derberg any thought about this?
There was a problem hiding this comment.
I do not know how/why link was incorrect, but I have accepted suggestion so now reference is working again
There was a problem hiding this comment.
@Florence-Njeri actually both are good - not sure where you see 404
I personally prefer full relative links like /docs/tools/generator/api but api works as well. Let's leave it as api as my approach for full relative links is an old habit that I follow but brainfart every time I try to find in my brain the reason for doing it 😄
| - <template>: Name of the generator template like for example @asyncapi/html-template or https://github.com/asyncapi/html-template | ||
| ARGUMENTS | ||
| ASYNCAPI - Local path, url or context-name pointing to AsyncAPI file | ||
| TEMPLATE - Name of the generator template like for example @asyncapi/html-template or https://github.com/asyncapi/html-template | ||
|
|
There was a problem hiding this comment.
@derberg correct me if I am wrong but I feel the changes being made to this file might be unnecessary especially this part asyncapi generate fromTemplate [ASYNCAPI] [TEMPLATE] [-h] [-d <value>] [-i] [--debug] [-n <value>] [-o <value>] [--force-write] [-w] [-p <value>] [--map-base-url <value>] why not just leave it as was asyncapi generate fromTemplate <asyncapi> <template> [<options>]
There was a problem hiding this comment.
See earlier argument. Keep documentation in sync with help-output generated from code
There was a problem hiding this comment.
yeah, I think in this particular case good to follow the output from CLI that is following best practices
| - <asyncapi>: Local path or URL pointing to AsyncAPI document for example https://bit.ly/asyncapi | ||
| - <template>: Name of the generator template like for example @asyncapi/html-template or https://github.com/asyncapi/html-template | ||
| ARGUMENTS | ||
| ASYNCAPI - Local path, url or context-name pointing to AsyncAPI file |
There was a problem hiding this comment.
Hi @Florence-Njeri , @derberg
I did "construct" my update by copy/pasting output of asyncapi generate fromTemplate --help. The suggestions break alignment between code and documentation. Do you really want to go that direction?
Alternative: apply suggestions to code (help text) and documentation in parallel. @derberg, can you point me to the help text?
Bring forward fix to 404 error Co-authored-by: Florence Njeri <[email protected]>
|
This is my second PR ever, so apologies where I behave in unexpected ways. Please coach me |
|
Hey @eelcofolkertsma no, you are doing amazing and the continuous improvements to our docs are a great help to our community. Let me take a nother look from your latest feedback |
|
@eelcofolkertsma great contributions so far 👏🏼 |
There was a problem hiding this comment.
Hey @eelcofolkertsma I took another look at your PR and it looks good. Good job and thank you for providing some extra context in the comments
|
|
/rtm |
|
🎉 This PR is included in version 1.17.18 🎉 The release is available on: Your semantic-release bot 📦🚀 |
To reflect changes in asyncapi generate fromTemplate command for --watch option
Documentation update to follow
asyncapi generate fromTemplate --help