Update Track 2 package Examples to leverage admonition directive.

[scbedd]

Context

Our examples are not rendering properly on docs.microsoft.com. Given our timelines, the docs team will not be able to make adjustments to support the pure literalinclude that we currently use.

To account for this, we need to surround our literalincludes with admonition directives. Details follow.

Direction

The issue here isn't that we are doing anything specifically wrong so much as different from what the doc team's CI pipelines ingestion requirements.

Details from Doc's Team Documentation

Example of Current Non-Compatible Code

This is the Source for additional context.

    Example:
        .. literalinclude:: ../examples/test_example_sync.py
            :start-after: [START build_pipeline]
            :end-before: [END build_pipeline]
            :language: python
            :dedent: 4
            :caption: Builds the pipeline for synchronous transport.

Example of New, Compatible Code

The above code has been transformed exactly as necessary to render properly. Note the sensitivity of a whitespace line between the literalinclude and the admonition directive.

The whitespace is also consistent between these two examples. If you run tox -e sphinx -c ../../../eng/tox/tox.ini you should be able to ensure that your example is rendering properly. It should look something like this:

    .. admonition:: Example:
    
        .. literalinclude:: ../examples/test_example_sync.py
            :start-after: [START build_pipeline]
            :end-before: [END build_pipeline]
            :language: python
            :dedent: 4
            :caption: Builds the pipeline for synchronous transport.

The goal is to ensure that your literalinclude is specified the same way as the above example.

Please work through your codebases, and give a checkbox for all updated. The examples should look like this:

Checklist

• azure-core
• azure-identity
• azure-keyvault-keys
• azure-keyvault-secrets
• azure-keyvault-certificates
• azure-storage-blob
• azure-storage-file
• azure-storage-queue
• azure-eventhub
• azure-eventhubs-checkpointstoreblob-aio

[scbedd]

I am working through an example render with the docs team to 100% confirm the above with a test run, please do not begin any changes on your local branches until I get a successful render using the methodology they recommended.

[bryevdv]

FWIW here is a one-liner that should handle the obvious cases:

find . -name '*.py' -print0 | xargs -0 perl -pi -e 's/^    Example:$/    \.\. admonition:: Example:\n/g'

[scbedd]

Den published an individual test pipeline to confirm my changes. Example is showing now!

I adjusted a single docstring in azure.core.pipeline, and that example is now rendering!

[scbedd]

All our packages do this now, as all our packages are showing example code sourced out of the package itself. 👍