From f44f5ee8787d322e0640d796211910ad165f9680 Mon Sep 17 00:00:00 2001
From: Adam Gayoso <adamgayoso@users.noreply.github.com>
Date: Tue, 7 Mar 2023 09:02:45 -0800
Subject: [PATCH] Update docs version (#154)

* No need for heading of attrs/methods

* sphinx book theme version

* add path to docs in conf

* drop autodoc typehints

* use sphinx ext autodoc

* add python to intersphinx mapping

* Back to sphinx_autodoc_typehints

* black

* restore conf.py

---------

Co-authored-by: Philipp A <flying-sheep@web.de>
---
 .../docs/_templates/autosummary/class.rst       |  6 ------
 {{cookiecutter.project_name}}/docs/conf.py      |  2 ++
 .../docs/extensions/typed_returns.py            | 17 ++++++++++-------
 {{cookiecutter.project_name}}/pyproject.toml    |  2 +-
 4 files changed, 13 insertions(+), 14 deletions(-)

diff --git a/{{cookiecutter.project_name}}/docs/_templates/autosummary/class.rst b/{{cookiecutter.project_name}}/docs/_templates/autosummary/class.rst
index 17dc123c..e4665dfc 100644
--- a/{{cookiecutter.project_name}}/docs/_templates/autosummary/class.rst
+++ b/{{cookiecutter.project_name}}/docs/_templates/autosummary/class.rst
@@ -39,9 +39,6 @@ Attributes
 
 {% for item in attributes %}
 
-{{ item }}
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
 .. autoattribute:: {{ [objname, item] | join(".") }}
 {%- endfor %}
 
@@ -56,9 +53,6 @@ Methods
 {% for item in methods %}
 {%- if item != '__init__' %}
 
-{{ item }}
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
 .. automethod:: {{ [objname, item] | join(".") }}
 {%- endif -%}
 {%- endfor %}
diff --git a/{{cookiecutter.project_name}}/docs/conf.py b/{{cookiecutter.project_name}}/docs/conf.py
index 923f04da..778eb13d 100644
--- a/{{cookiecutter.project_name}}/docs/conf.py
+++ b/{{cookiecutter.project_name}}/docs/conf.py
@@ -87,6 +87,7 @@
 }
 
 intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
     "anndata": ("https://anndata.readthedocs.io/en/stable/", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
 }
@@ -109,6 +110,7 @@
 html_theme_options = {
     "repository_url": repository_url,
     "use_repository_button": True,
+    "path_to_docs": "docs/",
 }
 
 pygments_style = "default"
diff --git a/{{cookiecutter.project_name}}/docs/extensions/typed_returns.py b/{{cookiecutter.project_name}}/docs/extensions/typed_returns.py
index 94478130..11352047 100644
--- a/{{cookiecutter.project_name}}/docs/extensions/typed_returns.py
+++ b/{{cookiecutter.project_name}}/docs/extensions/typed_returns.py
@@ -1,24 +1,27 @@
 # code from https://github.com/theislab/scanpy/blob/master/docs/extensions/typed_returns.py
 # with some minor adjustment
+from __future__ import annotations
+
 import re
+from collections.abc import Generator, Iterable
 
 from sphinx.application import Sphinx
 from sphinx.ext.napoleon import NumpyDocstring
 
 
-def _process_return(lines):
+def _process_return(lines: Iterable[str]) -> Generator[str, None, None]:
     for line in lines:
-        m = re.fullmatch(r"(?P<param>\w+)\s+:\s+(?P<type>[\w.]+)", line)
-        if m:
-            # Once this is in scanpydoc, we can use the fancy hover stuff
+        if m := re.fullmatch(r"(?P<param>\w+)\s+:\s+(?P<type>[\w.]+)", line):
             yield f'-{m["param"]} (:class:`~{m["type"]}`)'
         else:
             yield line
 
 
-def _parse_returns_section(self, section):
-    lines_raw = list(_process_return(self._dedent(self._consume_to_next_section())))
-    lines = self._format_block(":returns: ", lines_raw)
+def _parse_returns_section(self: NumpyDocstring, section: str) -> list[str]:
+    lines_raw = self._dedent(self._consume_to_next_section())
+    if lines_raw[0] == ":":
+        del lines_raw[0]
+    lines = self._format_block(":returns: ", list(_process_return(lines_raw)))
     if lines and lines[-1]:
         lines.append("")
     return lines
diff --git a/{{cookiecutter.project_name}}/pyproject.toml b/{{cookiecutter.project_name}}/pyproject.toml
index b16de456..592bc411 100644
--- a/{{cookiecutter.project_name}}/pyproject.toml
+++ b/{{cookiecutter.project_name}}/pyproject.toml
@@ -33,7 +33,7 @@ dev = [
 ]
 doc = [
     "sphinx>=4",
-    "sphinx-book-theme>=0.3.3",
+    "sphinx-book-theme>=1.0.0",
     "myst-nb",
     "sphinxcontrib-bibtex>=1.0.0",
     "sphinx-autodoc-typehints",