Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

APP-7160: viam module update CLI now accepts markdown_link and short_description for models #4672

Merged

Conversation

michaellee1019
Copy link
Member

This PR adds the ability for a developer to further explain the purpose and usage of each model within their module. short_description is a simple text field limited to 100 characters.

markdown_link is a bit more complicated: The link is a relative file path to where the CLI is ran. The purpose is to allow developers to write markdown documentation within their github repo that can be displayed when browsing their respository, and also show this markdown inline within the machine builder on app.viam.com (See the scope document for more details.

The markdown_link can include an anchor tag which links to a specific heading of the markdown content. In this case the content is parse and only the content within that section is consumed for that specific model. This feature allows developers to write a single markdown document for a module containing multiple models, and be able to show just the relevant section for the component/service being used on app.viam.com. In more detail, I've:

  • Done research and there does not seem to be a golang markdown parsing library.
  • Researched how Github generates anchor tags when you click on header links. And adhered to the same standards. The comments in generateAnchor should explain the rules. LMK if you have questions. The code also ensures that anchors are unique when there are duplicate header names, which Github also does.
  • Added tests for the various parsing situations.

In addition to tests I've ran the CLI locally and confirmed that the fields are correctly populated in MongoDB for my test module.

In the future:

  • We haven't decided yet if some content types should be stripped. This will be a followup ticket. I think we will likely strip relative images within markdown content and only allow hosted images. Needs more decision before implementing.
  • Additional PRs will be done to "encourage" adding these fields. But first we will finish the rest of the project and circle back to the

@michaellee1019 michaellee1019 requested a review from a team as a code owner January 3, 2025 16:47
@viambot viambot added the safe to test This pull request is marked safe to test from a trusted zone label Jan 3, 2025
@michaellee1019 michaellee1019 changed the title viam module update CLI now accepts markdown_link and short_description for models APP-7160: viam module update CLI now accepts markdown_link and short_description for models Jan 6, 2025
@michaellee1019
Copy link
Member Author

TY for the fast review!

@michaellee1019 michaellee1019 merged commit 310f4b6 into viamrobotics:main Jan 6, 2025
16 checks passed
@michaellee1019 michaellee1019 deleted the ml/cli-markdown-descr branch January 6, 2025 19:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
safe to test This pull request is marked safe to test from a trusted zone
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants