What about using python typing

[vallsv]

So now we are in Python 3.

What about changing the documentation guideline to use typing?

It's not about reworking everything, nor enforcing typing. It's just about changing the way we write documentation for the new code we design.

In Flint i mostly type everything. That's really useful. And as we already do it in the docstring, what about doing it with the python parser.

So this code:

    def getAlternativeImageData(self, copy=True):
        """Get the optional RGBA image that is displayed instead of the data

        :param bool copy: True (Default) to get a copy,
            False to use internal representation (do not modify!)
        :rtype: Union[None,numpy.ndarray]
        """
        pass

Can be written:

    def getAlternativeImageData(self, copy:bool=True) -> typing.Optional[numpy.ndarray]:
        """Get the optional RGBA image that is displayed instead of the data

        :param copy: True (Default) to get a copy,
            False to use internal representation (do not modify!)
        """
        pass

I dont have yet tried the result in sphinx.

What do you think?

[vasole]

Why am I always finding older code more readable?

I must be old :(

[t20100]

Would be nice to see how sphinx process it.

@vasole, I also find the function signature less readable (In the end, I guess you get used to it), but I also find the current docstring syntax to describe the type not really nicer either..

[vallsv]

Especially when you have to write :class:~bla.bla.bla.

To be honest, i use black, so i don't care much about the page layout. But i always use the autocompletion of the IDE, and here is a big difference, cause the python code is parsed and validated (flake, pylint), not the docstrings.

[vallsv]

So i did some tests. I checked 2 extensions (sphinx.ext.napoleon, sphinx-autodoc-typehints), and none provides links from arguments or returned type to the type description. So it's mostly useless for the HTML documentation.

[t20100]

Looking back into this, the sphinx-autodoc-typehints extension is doing it and it looks to work.

It is even packaged in ubuntu, conda-forge and debian but only from debian11 onward...

[t20100]

The answer is now de facto yes: there is some type hints in the code already Let's leverage this in the doc: See PR #3668.