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

[KeyVault] Use embedme to inject code snippets in README #7154

Closed
srnagar opened this issue Jan 6, 2020 · 4 comments · Fixed by #25441
Closed

[KeyVault] Use embedme to inject code snippets in README #7154

srnagar opened this issue Jan 6, 2020 · 4 comments · Fixed by #25441
Assignees
Labels
Client This issue points to a problem in the data-plane of the library. feature-request This issue requires a new behavior in the product in order be resolved. help wanted This issue is tracking work for which community contributions would be welcomed and appreciated KeyVault

Comments

@srnagar
Copy link
Member

srnagar commented Jan 6, 2020

READMEs are the first point of interaction for users looking to use our SDKs. It contains several useful code snippets for users to get started quickly. It is important to keep these code samples correct at all times. However, when code is modified README gets outdated and hard to figure out which README is referencing the modified piece of code.

Use https://github.com/zakhenry/embedme to embed code snippets from compilable Java files.

Code snippets in README

Samples in all README.md files should use compilable code to ensure they are updated when source code is updated. To do so, we use a utility tool to embed source code from Java files into README markdown files. Steps to add code snippets in README using the tool:

  • Download and install NodeJS
  • Create ReadmeSamples.java file in src/samples/java/ for which README.md should be updated
  • Add all the code snippets in the above Java file that should be included in README.md
  • Now, in README.md, add the embedme tag as shown below (the sample shows inserting code from line number 10 to 20)
<!-- embedme path/to/ReadmeSamples.java#L10-L20 -->
```java
```
  • To embed code using the tool, run the following command
npx embedme path/to/README.md
  • Verify the README.md file to confirm the samples are inserted as expected
@srnagar srnagar added KeyVault Client This issue points to a problem in the data-plane of the library. help wanted This issue is tracking work for which community contributions would be welcomed and appreciated labels Jan 6, 2020
@mclay
Copy link
Contributor

mclay commented Sep 25, 2020

please assign me this issue

@vcolin7
Copy link
Member

vcolin7 commented Sep 28, 2020

Thanks for the interest in this issue @mclay! It's assigned it to you :)

@vcolin7 vcolin7 added the feature-request This issue requires a new behavior in the product in order be resolved. label Sep 28, 2020
@vcolin7 vcolin7 added this to the Backlog milestone Mar 26, 2021
@vcolin7 vcolin7 self-assigned this Jun 17, 2021
@samvaity
Copy link
Member

samvaity commented Nov 2, 2021

Should we close this issue @vcolin7 ?

@vcolin7
Copy link
Member

vcolin7 commented Nov 2, 2021

@samvaity no, we haven't added code snippets to our Key Vault READMEs. I think this is something we can leave for MQ.

@github-actions github-actions bot locked and limited conversation to collaborators Apr 12, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Client This issue points to a problem in the data-plane of the library. feature-request This issue requires a new behavior in the product in order be resolved. help wanted This issue is tracking work for which community contributions would be welcomed and appreciated KeyVault
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants