search

Azure / azure-sdk-for-python

This repository is for active development of the Azure SDK for Python. For consumers of the SDK we recommend visiting our public developer docs at https://learn.microsoft.com/python/azure/ or our versioned developer docs at https://azure.github.io/azure-sdk-for-python.
MIT License
4.65k stars 2.84k forks source link

Create linter rule for ensuring proper Python crossreferences in docstrings #30169

Open rohit-ganguly opened 1 year ago

rohit-ganguly commented 1 year ago

Is your feature request related to a problem? Please describe. Due to incorrectly formatted docstrings, some Python reference docs that intend to cross-reference the Python documentation show up in weird formats on MS Learn. Attached is an example of this (from the azure-ai-ml library):

image

Describe the solution you'd like A linter rule to catch this and let contributors know that their docstrings need to be formatted correctly.

Describe alternatives you've considered N/A

Additional context This'll be a good quality of life win for our developers!

lmazuel commented 1 year ago

The problem is that people write List in docstring instead of list. Docstring are NOT type annotation, and people put type annotation there. Which breaks Sphinx.

rohit-ganguly commented 1 year ago

Just a few examples of xref issues in our docs across many libraries...

Needless to say given the prevalence of this issue, fixing this would be a great win for our docs.

l0lawrence commented 1 year ago

Add-on (after offside discussion): Potentially investigate updating Sphinx version to see if it helps this issue

kristapratico commented 10 months ago

I think it's possible we've understood this issue wrong. From local testing and comparing what I see on MS Learn and Github.io, this seems to be less about having type hints in docstrings and more about having bad cross-references for typing or forgetting to import the type used in the file. Maybe type hints breaking references was true some time ago, but it's possible that this has been fixed by bumping our Python / sphinx version in the docs build.

For example, here is the (working) doc from the example that Rohit posted in this issue's description:

https://learn.microsoft.com/en-us/python/api/azure-ai-ml/azure.ai.ml.automl.columntransformer?view=azure-python#constructor

@l0lawrence - did we rollout this pylint rule? I don't remember, but it looks like the linked PR was closed. I think we should hold off on adding a pylint rule for this until we understand it better.

That being said, @rohit-ganguly is this your understanding as well? Or did the docs team explicitly say something like "don't use type hints in docstrings"?

l0lawrence commented 10 months ago

We did not roll out a rule for this -- just other docstring improvement linters :)