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 <[email protected]>
scverse · Mar 7, 2023 · f44f5ee · f44f5ee
1 parent 81157a8
commit f44f5ee
Show file tree

Hide file tree

Showing 4 changed files with 13 additions and 14 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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",