README - compilable code snippets

[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.

So, this change will introduce a mechanism to inject code from a compiled Java class to ensure freshness of samples.

Tool used - https://github.com/zakhenry/embedme

How to use:

1. Install NodeJS if you don't already have it.
2. In README files, use the following language tag for all code snippets that you want to provide:

```java
```

3. Within the tag, add a comment (should be the only line) providing the path (relative to the README file) to the Java file containing the code snippet that you want to replace with.

// path/to/class/containing/Samples.java

4. A sub-section of the Java file can also be used by providing line numbers.

// path/to/class/containing/Samples.java#L20-L30

5. Next run the embedme tool as shown below:

npx embedme path/to/README.md

6. The code should now be inserted into the README file from the java class.
7. Verify the changes to the README file.

This PR is using this tool for

• Core libraries
• Identity

Partially fixes #6608

[JonathanGiles]

I like this a lot. It will help to ensure our samples are always accurate and compiling. I think introducing a new sample file (ReadmeSamples.java) is a good idea and should be used consistently, especially given the line referencing approach used in the markdown. I would recommend you introduce some warning text at the top of these files to warn users against making any changes to the code that may result in line number differences.

[alzimmermsft]

Would it be possible to update the Blob Batch README to use these? It already has a ReadmeCodeSamples class.

[alzimmermsft]

Need to update the exclusion regex here to include ReademeSamples classes.

https://github.com/Azure/azure-sdk-for-java/blob/master/eng/code-quality-reports/src/main/resources/spotbugs/spotbugs-exclude.xml#L558

[alzimmermsft]

Is there a way to hide this in the README?

[srnagar]

There is a way to hide but I like to leave it as it is so that we'll know where the snippets are coming from and leaving it here will allow for future updates to automatically pick up the changes.

[srnagar]

@JonathanGiles Added a warning message to ReadmeSamples.java to ensure line numbers are correct.
@alzimmermsft - Updated storage blob batch README to use the code snippets in java file.

[JonathanGiles]

You shouldn't need to explicitly call out the batch file should you?

[srnagar]

Removed it.

[JonathanGiles]

I agree with Alan, I'm not convinced that we want these to show up in all of the code samples. If we can hide it, whilst still retaining the ability for it to be updated when the sample code is changed, that would be best IMHO.

[srnagar]

Using alternate embedding syntax that will hide the comment in README and will continue to be updated when sample code changes.

[JonathanGiles]

Should we introduce tooling into /eng that would run this over all readme files?

[srnagar]

@JonathanGiles Yes, I will have a follow-up task to introduce tooling that will automatically run this to update READMEs. This PR is a first step to get everyone's thoughts on the tool and usage. If we want to go ahead with this, I will look into integrating with eng tools.