Question: Is include the _str_signature necessary in the __str__

[hmaarrfk]

numpydoc/numpydoc/docscrape.py

Line 471 in 659e43f

out += self._str_signature()

It doesn't seem natural for one to write their own signature. I would think that the str(NumpyDocString) would return the same thing that one would type themselves.

Can we take out the _str_signature?

Once again, this is in reference to designing a solution for:
#67 (comment)

Otherwise, one would need an other function that doesn't include the _str_signature() line.

[pv]

No, if the original docstring contained the signature also the formatted one needs to contain it.

[hmaarrfk]

I guess the question relates to roundtripping (PR #189):

# Signature example

from numpydoc.docscrape import FunctionDoc

def foo(bar='baz'):
    """foo does foo-like stuff

    Parameters
    ----------
    bar : str
        bar like stufff

    """
    return bar


doc = FunctionDoc(foo)

print(str(doc))

output:

.. function:: foo
    

foo(bar='baz')

foo does foo-like stuff

Parameters
----------
bar : str
    bar like stufff

.. index::

I expected it to return something like the original doc-string I typed in.

I understand if this isn't the desired usecase of numpydoc.

I understand if this

[pv]

Perhaps --- however, please keep in mind that numpydoc has a single task that it is meant to do, generating Sphinx-formatted docstrings from Numpy-format ones, and any changes should not cause regressions to this functionality.

[hmaarrfk]

Got it. I'll keep that in mind when I try to think of a good way to integrate this kind of functionality.