search

Azure / autorest.python

Extension for AutoRest (https://github.com/Azure/autorest) that generates Python code
MIT License
80 stars 57 forks source link

Duplicate link target sphinx warning #2828

Open catalinaperalta opened 1 month ago

catalinaperalta commented 1 month ago

sphinx doesnt like it when we have links with the same link target.

Example of a service that ran into this issue: Tsp link target 1: https://github.com/Azure/azure-rest-api-specs/blob/d37c97f182cd797cee5ddd853e66cb6d78b52f0b/specification/ai/HealthInsights/HealthInsights.Common/model.common.fhir.elements.tsp#L58 Tsp link target 2: https://github.com/Azure/azure-rest-api-specs/blob/d37c97f182cd797cee5ddd853e66cb6d78b52f0b/specification/ai/HealthInsights/HealthInsights.Common/model.common.fhir.elements.tsp#L75

Python generated code: link target 1 and link target 2

There can be many instances like in the example above where a service will want to use the same link target and the documentation is clear in this case. However, duplicate link targets cause sphinx checks to fail with the following warning:

image

Possible solution: if we can generate links with 2 underscores instead of just 1 that will make the link targets anonymous and allows sphinx checks to pass.

msyyc commented 1 month ago

Since python uses m2r2 to convert .md doc to .rst doc which is for sphinx so it is hard to update the codegen for specific docstrings. Is it possible to update typespec? For example, makes another display name [FHIR Element doc](https://www.hl7.org/fhir/R4/element.html).