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