Skip to content

Non-functions in the See Also section #618

Open
@crusaderky

Description

@crusaderky

The See Also section should be explicitly allowed to contain references to any object.

The current situation is murky:

  • The documentation exclusively mentions functions, without explicitly ruling out other entities.
    https://numpydoc.readthedocs.io/en/latest/format.html#see-also
  • numpydoc parses untagged entries in the section to match anything
  • numpydoc.docscrape automatically adds the :func: tag to untagged entries, but otherwise accepts other entries.

This causes problems for example with numpy/numpy#28734.
This works with intersphinx:

def f():
    """
    See Also
    --------
    numpy.logaddexp
    """

However, a round-trip through docscrape breaks it:

def f():
    """
    See Also
    --------
    numpy.logaddexp
    """

from numpydoc.docscrape import FunctionDoc
f.__doc__ = str(FunctionDoc(f))

Now f.__doc__ has been changed to

.. function:: f
    




See Also
--------

:func:`numpy.logaddexp`
    ..

Which encroaches on numpy/numpy#28734 and breaks the rendering, because numpy.logaddexp is actually a py:data object.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions