Skip to content

[Text Analytics] Use embedme to inject code snippets in README #7153

Description

@srnagar

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

Metadata

Metadata

Assignees

Labels

ClientThis issue points to a problem in the data-plane of the library.Cognitive - Text Analytics

Type

No type

Fields

No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions