Improve line numbers for docstrings

[dimaqq]

I get warnings like this:

/code/operator/ops/__init__.py:docstring of ops:42: WARNING: py:attr reference target not found: ...

The thing is, the file starts with a large comment preamble (you may use this software...) and line 42 of the docstring corresponds to line 56 of the file in my case.

Which means that for large multiline docstrings, the docstring line number is not very useful.

Could Sphinx show this instead?

/code/operator/ops/__init__.py:56: docstring of ops: WARNING: py:attr reference target not found: ...

[picnixz]

We don't necessarily know where the oroginal docstring is so I'm not sure we can actually do it. If you manually specify a docstring via __doc__, we won't know the offset. And we cannot distinguish (easily) a "static" docstring from a dynamic one.

It's possible to do it by improving the static analysis but it's hard I think. Nonetheless maybe we do record where the docs are being added though.

In addition, there is also the possibility for the docstring to be altered by some event handler so we also need to keep track of each docstring state which might blow up the memory usage (which is already massive).

[dimaqq]

Ahh I didn’t think about that.

Let me ask Python ideas.

[dimaqq]

https://discuss.python.org/t/would-it-be-awesome-if-docstrings-were-stamped-with-where-they-were-defined/64667

[picnixz]

It's not really a Python issue. It's just that we have a limited static analysis and that we need to improve it on our side.

It's probably possible to have the real line number but it'll be a not-so-simple task!