update doc

Author: j-bac

doc/_templates/autosummary/base.rst

@@ -0,0 +1,7 @@
+:github_url: {{ fullname | modurl }}
+
+{{ fullname | api_image }}
+
+{% extends "!autosummary/base.rst" %}
+
+.. http://www.sphinx-doc.org/en/stable/ext/autosummary.html#customizing-templates

doc/_templates/autosummary/class.rst

@@ -0,0 +1,33 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. add toctree option to make autodoc generate the pages
+
+.. autoclass:: {{ objname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Attributes
+
+   .. autosummary::
+      :toctree: .
+   {% for item in attributes %}
+      ~{{ fullname }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: Methods
+
+   .. autosummary::
+      :toctree: .
+   {% for item in methods %}
+      {%- if item != '__init__' %}
+      ~{{ fullname }}.{{ item }}
+      {%- endif -%}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

doc/conf.py

@@ -32,6 +32,11 @@
     "numpydoc",
 ]
 
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = False
+napoleon_use_rtype = False
+napoleon_custom_sections = [("Params", "Parameters")]
 
 # this is needed for some reason...
 # see https://github.com/numpy/numpydoc/issues/69
@@ -63,8 +68,8 @@
 # The master toctree document.
 master_doc = "index"
 
-project = u"scikit-dimension"
-copyright = u"2020, Jonathan Bac"
+project = "scikit-dimension"
+copyright = "2020, Jonathan Bac"
 
 # The short X.Y version.
 version = __version__
@@ -216,8 +221,8 @@
     (
         "index",
         "scikit-dimension.tex",
-        u"scikit-dimension Documentation",
-        u"Jonathan Bac",
+        "scikit-dimension Documentation",
+        "Jonathan Bac",
         "manual",
     ),
 ]
@@ -313,3 +318,241 @@
 def setup(app):
     # a copy button to copy snippet of code from the documentation
     app.add_stylesheet("css/custom.css")
+
+
+# -- Options for other output ------------------------------------------
+import inspect
+from pathlib import Path
+from typing import Optional, Union, Mapping
+import logging
+from sphinx.application import Sphinx
+from sphinx.ext import autosummary
+
+logger = logging.getLogger(__name__)
+author = "Jonathan Bac"
+title = "scikit_dimension"
+title_doc = f"{project} documentation"
+
+latex_documents = [(master_doc, f"{project}.tex", title_doc, author, "manual")]
+man_pages = [(master_doc, project, title_doc, [author], 1)]
+texinfo_documents = [
+    (master_doc, project, title_doc, author, project, title, "Miscellaneous")
+]
+
+
+# -- generate_options override ------------------------------------------
+
+
+def process_generate_options(app: Sphinx):
+    genfiles = app.config.autosummary_generate
+
+    if genfiles and not hasattr(genfiles, "__len__"):
+        env = app.builder.env
+        genfiles = [
+            env.doc2path(x, base=None)
+            for x in env.found_docs
+            if Path(env.doc2path(x)).is_file()
+        ]
+    if not genfiles:
+        return
+
+    from sphinx.ext.autosummary.generate import generate_autosummary_docs
+
+    ext = app.config.source_suffix
+    genfiles = [
+        genfile + (not genfile.endswith(tuple(ext)) and ext[0] or "")
+        for genfile in genfiles
+    ]
+
+    suffix = autosummary.get_rst_suffix(app)
+    if suffix is None:
+        return
+
+    generate_autosummary_docs(
+        genfiles,
+        builder=app.builder,
+        warn=logger.warning,
+        info=logger.info,
+        suffix=suffix,
+        base_path=app.srcdir,
+        imported_members=True,
+        app=app,
+    )
+
+
+autosummary.process_generate_options = process_generate_options
+
+
+# -- GitHub URLs for class and method pages ------------------------------------------
+
+
+def get_obj_module(qualname):
+    """Get a module/class/attribute and its original module by qualname"""
+    modname = qualname
+    classname = None
+    attrname = None
+    while modname not in sys.modules:
+        attrname = classname
+        modname, classname = modname.rsplit(".", 1)
+
+    # retrieve object and find original module name
+    if classname:
+        cls = getattr(sys.modules[modname], classname)
+        modname = cls.__module__
+        obj = getattr(cls, attrname) if attrname else cls
+    else:
+        obj = None
+
+    return obj, sys.modules[modname]
+
+
+def get_linenos(obj):
+    """Get an object’s line numbers"""
+    try:
+        lines, start = inspect.getsourcelines(obj)
+    except TypeError:
+        return None, None
+    else:
+        return start, start + len(lines) - 1
+
+
+# set project_dir: project/docs/source/conf.py/../../.. → project/
+project_dir = Path(__file__).parent.parent.parent
+github_url_scvelo = "https://github.com/j-bac/scikit-dimension/tree/master"
+from pathlib import PurePosixPath
+
+
+def modurl(qualname):
+    """Get the full GitHub URL for some object’s qualname."""
+    obj, module = get_obj_module(qualname)
+    github_url = github_url_scvelo
+    # try:
+    path = PurePosixPath(Path(module.__file__).resolve().relative_to(project_dir))
+    # except ValueError:
+    # trying to document something from another package
+    # github_url = (
+    #    if "read" in qualname
+    # )
+    # path = "/".join(module.__file__.split("/")[-2:])
+    start, end = get_linenos(obj)
+    fragment = f"#L{start}-L{end}" if start and end else ""
+    return f"{github_url}/{path}{fragment}"
+
+
+def api_image(qualname: str) -> Optional[str]:
+    path = Path(__file__).parent / f"{qualname}.png"
+    print(path, path.is_file())
+    return (
+        f".. image:: {path.name}\n   :width: 200\n   :align: right"
+        if path.is_file()
+        else ""
+    )
+
+
+# modify the default filters
+from jinja2.defaults import DEFAULT_FILTERS
+
+DEFAULT_FILTERS.update(modurl=modurl, api_image=api_image)
+
+# -- Override some classnames in autodoc --------------------------------------------
+
+import sphinx_autodoc_typehints
+
+qualname_overrides = {
+    "anndata.base.AnnData": "anndata.AnnData",
+}
+
+fa_orig = sphinx_autodoc_typehints.format_annotation
+
+
+def format_annotation(annotation):
+    if getattr(annotation, "__origin__", None) is Union or hasattr(
+        annotation, "__union_params__"
+    ):
+        params = getattr(annotation, "__union_params__", None) or getattr(
+            annotation, "__args__", None
+        )
+        return ", ".join(map(format_annotation, params))
+    if getattr(annotation, "__origin__", None) is Mapping:
+        return ":class:`~typing.Mapping`"
+    if inspect.isclass(annotation):
+        full_name = f"{annotation.__module__}.{annotation.__qualname__}"
+        override = qualname_overrides.get(full_name)
+        if override is not None:
+            return f":py:class:`~{qualname_overrides[full_name]}`"
+    return fa_orig(annotation)
+
+
+sphinx_autodoc_typehints.format_annotation = format_annotation
+
+
+# -- Prettier Param docs --------------------------------------------
+
+from typing import Dict, List, Tuple
+from docutils import nodes
+from sphinx import addnodes
+from sphinx.domains.python import PyTypedField, PyObject
+from sphinx.environment import BuildEnvironment
+
+
+class PrettyTypedField(PyTypedField):
+    list_type = nodes.definition_list
+
+    def make_field(
+        self,
+        types: Dict[str, List[nodes.Node]],
+        domain: str,
+        items: Tuple[str, List[nodes.inline]],
+        env: BuildEnvironment = None,
+    ) -> nodes.field:
+        def makerefs(rolename, name, node):
+            return self.make_xrefs(rolename, domain, name, node, env=env)
+
+        def handle_item(
+            fieldarg: str, content: List[nodes.inline]
+        ) -> nodes.definition_list_item:
+            head = nodes.term()
+            head += makerefs(self.rolename, fieldarg, addnodes.literal_strong)
+            fieldtype = types.pop(fieldarg, None)
+            if fieldtype is not None:
+                head += nodes.Text(" : ")
+                if len(fieldtype) == 1 and isinstance(fieldtype[0], nodes.Text):
+                    (text_node,) = fieldtype  # type: nodes.Text
+                    head += makerefs(
+                        self.typerolename, text_node.astext(), addnodes.literal_emphasis
+                    )
+                else:
+                    head += fieldtype
+
+            body_content = nodes.paragraph("", "", *content)
+            body = nodes.definition("", body_content)
+
+            return nodes.definition_list_item("", head, body)
+
+        fieldname = nodes.field_name("", self.label)
+        if len(items) == 1 and self.can_collapse:
+            fieldarg, content = items[0]
+            bodynode = handle_item(fieldarg, content)
+        else:
+            bodynode = self.list_type()
+            for fieldarg, content in items:
+                bodynode += handle_item(fieldarg, content)
+        fieldbody = nodes.field_body("", bodynode)
+        return nodes.field("", fieldname, fieldbody)
+
+
+# replace matching field types with ours
+PyObject.doc_field_types = [
+    PrettyTypedField(
+        ft.name,
+        names=ft.names,
+        typenames=ft.typenames,
+        label=ft.label,
+        rolename=ft.rolename,
+        typerolename=ft.typerolename,
+        can_collapse=ft.can_collapse,
+    )
+    if isinstance(ft, PyTypedField)
+    else ft
+    for ft in PyObject.doc_field_types
+]

doc/requirements.txt

@@ -8,4 +8,4 @@ ipykernel
 sphinx>=1.7
 nbsphinx>=0.7
 numpydoc
-pandoc
+pandoc

doc/skdim.datasets.BenchmarkManifolds.generate.rst

@@ -0,0 +1,10 @@
+:github_url: https://github.com/theislab/scvelo/tree/master/scikit-dimension/skdim/datasets.py#L383-L436
+
+
+
+skdim.datasets.BenchmarkManifolds.generate
+==========================================
+
+.. currentmodule:: skdim.datasets
+
+.. automethod:: BenchmarkManifolds.generate

doc/skdim.datasets.BenchmarkManifolds.rst

@@ -3,18 +3,22 @@ skdim.datasets.BenchmarkManifolds
 
 .. currentmodule:: skdim.datasets
 
+.. add toctree option to make autodoc generate the pages
+
 .. autoclass:: BenchmarkManifolds
 
 
-   .. automethod:: __init__
+   
+   
 
 
+   
    .. rubric:: Methods
 
    .. autosummary::
+      :toctree: .
 
-      ~BenchmarkManifolds.__init__
-      ~BenchmarkManifolds.generate
+      ~skdim.datasets.BenchmarkManifolds.generate
 
 
 

doc/skdim.datasets.hyperBall.rst

@@ -1,3 +1,7 @@
+:github_url: https://github.com/theislab/scvelo/tree/master/scikit-dimension/skdim/datasets.py#L38-L69
+
+
+
 skdim.datasets.hyperBall
 ========================
 

doc/skdim.datasets.hyperSphere.rst

@@ -1,3 +1,7 @@
+:github_url: https://github.com/theislab/scvelo/tree/master/scikit-dimension/skdim/datasets.py#L72-L95
+
+
+
 skdim.datasets.hyperSphere
 ==========================
 

doc/skdim.datasets.hyperTwinPeaks.rst

@@ -1,3 +1,7 @@
+:github_url: https://github.com/theislab/scvelo/tree/master/scikit-dimension/skdim/datasets.py#L98-L122
+
+
+
 skdim.datasets.hyperTwinPeaks
 =============================
 

doc/skdim.datasets.lineDiskBall.rst

@@ -1,3 +1,7 @@
+:github_url: https://github.com/theislab/scvelo/tree/master/scikit-dimension/skdim/datasets.py#L125-L187
+
+
+
 skdim.datasets.lineDiskBall
 ===========================