Add prose extension for numpydoc (#116)

Author: flying-sheep

docs/_templates/autosummary/module.rst

@@ -0,0 +1,40 @@
+{# https://raw.githubusercontent.com/sphinx-doc/sphinx/master/sphinx/ext/autosummary/templates/autosummary/module.rst #}
+{% extends "!autosummary/module.rst" %}
+
+{% block classes %}
+{% if classes -%}
+Classes
+-------
+
+{%- for class in classes -%}
+{%- if not class.startswith('_') %}
+.. autoclass:: {{ class }}
+   :members:
+{%- endif -%}
+{%- endfor -%}
+{%- endif %}
+{% endblock %}
+
+{% block functions %}
+{% if functions -%}
+Functions
+---------
+
+{%- for function in functions -%}
+{%- if not function.startswith('_') and not function.startswith('example_') %}
+.. autofunction:: {{ function }}
+{%- endif -%}
+{%- endfor -%}
+{%- if functions | select('search', '^example_') | first %}
+
+Examples
+--------
+
+{%- for function in functions -%}
+{%- if function.startswith('example_') %}
+.. autofunction:: {{ function }}
+{%- endif -%}
+{%- endfor -%}
+{%- endif -%}
+{%- endif %}
+{% endblock %}

docs/conf.py

@@ -8,6 +8,8 @@
 from datetime import timezone as tz
 from importlib.metadata import metadata
 
+from jinja2.tests import TESTS
+
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
@@ -51,6 +53,20 @@
 # Don’t add module paths to documented functions’ names
 add_module_names = False
 
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+
+
+def test_search(value: str, pattern: str) -> bool:
+    """Tests if `pattern` can be found in `value`."""
+    import re
+
+    return bool(re.search(pattern, value))
+
+
+# IDK if there’s a good way to do this without modifying the global list
+TESTS["search"] = test_search
+
 html_theme = "scanpydoc"
 html_theme_options = dict(
     repository_url="https://github.com/theislab/scanpydoc",

pyproject.toml

@@ -72,11 +72,14 @@ ignore = [
 ]
 [tool.ruff.lint.flake8-type-checking]
 strict = true
+exempt-modules = []
 [tool.ruff.lint.isort]
 length-sort = true
 lines-after-imports = 2
 known-first-party = ['scanpydoc']
 required-imports = ["from __future__ import annotations"]
+[tool.ruff.lint.pydocstyle]
+convention = 'numpy'
 
 [tool.mypy]
 strict = true

src/scanpydoc/__init__.py

@@ -20,11 +20,14 @@
 # Can’t seem to be able to do this in numpydoc style:
 # https://github.com/sphinx-doc/sphinx/issues/5887
 setup_sig_str = """\
-Args:
-    app: Sphinx app to set this :term:`sphinx:extension` up for
-
-Returns:
-    :ref:`Metadata <sphinx:ext-metadata>` for this extension.
+Arguments
+---------
+app
+    Sphinx app to set this :term:`sphinx:extension` up for
+
+Returns
+-------
+:ref:`Metadata <sphinx:ext-metadata>` for this extension.
 """
 
 C = TypeVar("C", bound=Callable[..., Any])

src/scanpydoc/autosummary_generate_imported.py

@@ -7,19 +7,19 @@
 
 from __future__ import annotations
 
-import sys
 from typing import TYPE_CHECKING
 
-
-if sys.version_info >= (3, 11):
-    from typing import Never
-else:  # pragma: no cover
-    from typing import NoReturn as Never
-
 from . import _setup_sig
 
 
 if TYPE_CHECKING:
+    import sys
+
+    if sys.version_info >= (3, 11):
+        from typing import Never
+    else:  # pragma: no cover
+        from typing import NoReturn as Never
+
     from sphinx.application import Sphinx
 
 

src/scanpydoc/elegant_typehints/__init__.py

@@ -47,26 +47,28 @@ def x() -> Tuple[int, float]:
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 from pathlib import Path
 from collections import ChainMap
 from dataclasses import dataclass
 
 from sphinx.ext.autodoc import ClassDocumenter
+from sphinx.ext.napoleon import NumpyDocstring  # type: ignore[attr-defined]
 
 from scanpydoc import metadata, _setup_sig
 
-from .example import example_func
+from .example import example_func_prose, example_func_tuple
 
 
 if TYPE_CHECKING:
+    from typing import Any
     from collections.abc import Callable
 
     from sphinx.config import Config
     from sphinx.application import Sphinx
 
 
-__all__ = ["example_func", "setup"]
+__all__ = ["example_func_prose", "example_func_tuple", "setup"]
 
 
 HERE = Path(__file__).parent.resolve()
@@ -123,7 +125,9 @@ def setup(app: Sphinx) -> dict[str, Any]:
     )
 
     from ._return_tuple import process_docstring  # , process_signature
+    from ._return_patch_numpydoc import _parse_returns_section
 
+    NumpyDocstring._parse_returns_section = _parse_returns_section  # type: ignore[method-assign,assignment]  # noqa: SLF001
     app.connect("autodoc-process-docstring", process_docstring)
 
     return metadata

src/scanpydoc/elegant_typehints/_formatting.py

@@ -2,7 +2,7 @@
 
 import sys
 import inspect
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 
 if sys.version_info >= (3, 10):
@@ -15,6 +15,8 @@
 
 
 if TYPE_CHECKING:
+    from typing import Any
+
     from sphinx.config import Config
 
 
@@ -24,12 +26,16 @@ def typehints_formatter(annotation: type[Any], config: Config) -> str | None:
     Can be used as ``typehints_formatter`` for :mod:`sphinx_autodoc_typehints`,
     to respect the ``qualname_overrides`` option.
 
-    Args:
-        annotation: A type or class used as type annotation.
-        config: Sphinx config containing ``sphinx-autodoc-typehints``’s options.
+    Arguments
+    ---------
+    annotation
+        A type or class used as type annotation.
+    config
+        Sphinx config containing ``sphinx-autodoc-typehints``’s options.
 
-    Returns:
-        reStructuredText describing the type
+    Returns
+    -------
+    reStructuredText describing the type
     """
     if inspect.isclass(annotation) and annotation.__module__ == "builtins":
         return None

src/scanpydoc/elegant_typehints/_return_patch_numpydoc.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+
+if TYPE_CHECKING:
+    from sphinx.ext.napoleon import NumpyDocstring  # type: ignore[attr-defined]
+
+__all__ = ["_parse_returns_section"]
+
+
+def _parse_returns_section(self: NumpyDocstring, section: str) -> list[str]:  # noqa: ARG001
+    lines_raw = list(self._dedent(self._consume_to_next_section()))
+    if lines_raw[0] == ":":
+        # Remove the “:” inserted by sphinx-autodoc-typehints
+        # https://github.com/tox-dev/sphinx-autodoc-typehints/blob/a5c091f725da8374347802d54c16c3d38833d41c/src/sphinx_autodoc_typehints/patches.py#L66
+        lines_raw.pop(0)
+    lines = self._format_block(":returns: ", lines_raw)
+    if lines and lines[-1]:
+        lines.append("")
+    return lines

src/scanpydoc/elegant_typehints/_return_tuple.py

@@ -3,14 +3,15 @@
 import re
 import sys
 import inspect
-from typing import TYPE_CHECKING, Any, Union, get_args, get_origin, get_type_hints
+from typing import TYPE_CHECKING, Union, get_args, get_origin, get_type_hints
 from typing import Tuple as t_Tuple  # noqa: UP035
 from logging import getLogger
 
 from sphinx_autodoc_typehints import format_annotation
 
 
 if TYPE_CHECKING:
+    from typing import Any
     from collections.abc import Sequence
 
     from sphinx.application import Sphinx

src/scanpydoc/elegant_typehints/example.py

@@ -1,17 +1,33 @@
 from __future__ import annotations
 
 
-def example_func(
+def example_func_prose(
     a: str | None, b: str | int | None = None
 ) -> dict[str, int]:  # pragma: no cover
-    """Example function.
+    """Example function with a paragraph return section.
 
-    Hover over the parameter and return type annotations to see the long versions.
+    Parameters
+    ----------
+    a
+        An example parameter
+    b
+        Another, with a default
 
-    Args:
-        a: An example parameter
-        b: Another, with a default
-    Returns:
-        An example return value
+    Returns
+    -------
+    An example dict
     """
     return {}
+
+
+def example_func_tuple() -> tuple[int, str]:  # pragma: no cover
+    """Example function with return tuple.
+
+    Returns
+    -------
+    x
+        An example int
+    y
+        An example str
+    """
+    return (1, "foo")