Several package docs at https://azure.github.io/azure-sdk-for-python/ have cross-references to classes that do not render properly, e.g.:

• https://azure.github.io/azure-sdk-for-python/ref/azure.eventhub.html#azure.eventhub.consumer.EventHubConsumer.receive

• https://azure.github.io/azure-sdk-for-python/ref/azure.servicebus.html#azure.servicebus.servicebus_client.ServiceBusClient.get_queue

• https://azure.github.io/azure-sdk-for-python/ref/azure.storage.queue.html#azure.storage.queue.queue_client.QueueClient.create_queue

• https://azure.github.io/azure-sdk-for-python/ref/azure.keyvault.secrets.html#azure.keyvault.secrets.client.SecretClient.backup_secret

(This list is not exhaustive, just specific examples in different packages)

I made a small PR to fix this in keyvault: #7215 using explicit directives:

:class:`~foo.Bar`

etc. But noted that although things work with this change, the rendered appearance is also different from the "implicitly" rendered cross reference links (I guess these are generated by sphinx-apidoc?) i.e.

VS

The second version is the version with explicit :class: (though without a leading tilde to shorten) and is apparently used already in some SDKs. I am not sure how else to fix this problem except to use explicit directives, and FWIW I have only ever used explicit directives in the past.