napoleon: docstrings do not produce type annotations

[eric-wieser]

As seen in this test:

sphinx/tests/test_ext_napoleon_docstring.py

Lines 46 to 75 in 6cb3391

	class NamedtupleSubclassTest(BaseDocstringTest):
	def test_attributes_docstring(self):
	config = Config()
	actual = str(NumpyDocstring(cleandoc(NamedtupleSubclass.__doc__),
	config=config, app=None, what='class',
	name='NamedtupleSubclass', obj=NamedtupleSubclass))
	expected = """\
	Sample namedtuple subclass
	.. attribute:: attr1
	Quick description of attr1
	:type: Arbitrary type
	.. attribute:: attr2
	Quick description of attr2
	:type: Another arbitrary type
	.. attribute:: attr3
	Adds a newline after the type
	:type: Type
	"""
	self.assertEqual(expected, actual)

sphinx.ext.napoleon results in rST with :type: at the end of each .. attribute:::

 .. attribute:: attr1 
  
    Quick description of attr1 
  
    :type: Arbitrary type

However, for these to render correctly as type annotations, this should generate

 .. attribute:: attr1 
    :type: Arbitrary type 
  
    Quick description of attr1 

I think this is a historical accident - the :type: option for the attribute directive was added only in Sphinx 2.4, but the :type:` field has been around for a long time.

Graphically, the approaches in the two code blocks above result in the two styles visible in this image:

[francoislauger]

I found that adding this setting for napoleon in conf.py give me the desired result :

# Otherwise, the Attributes parameter list looks different from the Parameters list
napoleon_use_ivar = True

I can't find were I found this solution.

[tk0miya]

Yes, it was overlooked on updating 2.4. But I don't know this is good for numpydoc because the format allows many kinds of type-hints like string. see https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard. They are not compatible with PEP 484 based type annotations.

[eric-wieser]

Does it matter if the type description is parseable as PEP 484? Presumably sphinx just spits our the raw text if parsing fails.

[eric-wieser]

For this docstring example from your link:

filename : str
copy : bool
dtype : data-type
iterable : iterable object
shape : int or tuple of int
files : list of str

Here's the results before and after this change:

Before	After

The before rendering is just way too clutted in my opinion, and the after looks way better to me.

[tk0miya]

Does it matter if the type description is parseable as PEP 484? Presumably sphinx just spits our the raw text if parsing fails.

There are two worries. 1) A variable declaration in name: type form looks like PEP 484. So I consider the type is a type hints. But data-type, iterable object, array_like and etc. are not. So I feel strange. 2) The type annotations for py:function and other directives are converted to cross-reference. At present, :type: option for py:attribute directive is not converted yet. But it will support soon. If so, that causes nitpicky-warning if non-python objects as a type description.

To be clear, I don't object to your idea strongly. I understand current formatting is not good, as you said.

[tk0miya]

I reconsidered this and I feel this does not harm nobody. So +1 for this.

[eric-wieser]

I don't think we should close this yet. The following code (derived from https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html#example-google) still produces the old output format:

class Foo:
    def __init__(self):
        #: list(str): Doc comment *before* attribute, with type specified
        self.attr4 = ['attr4']

I wasn't sure how to fix this - the hook for parsing the comment doesn't appear to have the capability to set option flags on directives.

[tk0miya]

The comment notation is not a part of google style and numpy style. So it is not responsibility of napoleon extension. I consider another topic. Additionally, we have variable type annotations now in python 3.6. So I think not so worthy to support it.

[tk0miya]

My worry is realized and causes #7808 . So I reverted #7583 in #7827. So we should reconsider this again.

2. The type annotations for py:function and other directives are converted to cross-reference. At present, :type: option for py:attribute directive is not converted yet. But it will support soon. If so, that causes nitpicky-warning if non-python objects as a type description.

[tk0miya]

I think many people use numpy-format type descriptions that is written by natural language, not compatible with PEP-484 style type annotations. So it would be better to add a new option to enable this feature. I can accept it if we'll reach a good name.