Merge pull request #124 from icbi-lab/improve-apidoc2

Improve API documentation

.gitignore

@@ -2,6 +2,7 @@
 !.vscode/settings.json.default
 notebooks
 tutorial
+.idea
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

docs/_templates/autosummary/base.rst

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

docs/_templates/autosummary/class.rst

@@ -0,0 +1,35 @@
+:github_url: {{ fullname | github_url }}
+
+{{ 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 %}

docs/api.rst

@@ -1,11 +1,24 @@
 API
 ===
 
+Import scirpy together with scanpy as 
+
+.. code-block:: python
+
+   import scanpy as sc   
+   import scirpy as ir
+
+For consistency, the scirpy API tries to follow the `scanpy API <https://scanpy.readthedocs.io/en/stable/api/index.html>`__
+as closely as possible. 
+
 .. _api-io:
 
 Input/Output
 ------------
 
+The following functions allow to import :term:`V(D)J` information from various
+formats. See also :ref:`importing-data`. 
+
 .. module:: scirpy
 
 .. autosummary::
@@ -16,19 +29,6 @@ Input/Output
    read_tracer
 
 
-Datasets: `datasets`
---------------------
-
-.. module:: scirpy.datasets
-
-.. autosummary::
-   :toctree: .
-
-   wu2020
-   wu2020_3k
-
-
-
 Preprocessing: `pp`
 -------------------
 
@@ -38,35 +38,79 @@ Preprocessing: `pp`
    :toctree: .
 
    merge_with_tcr
-   tcr_dist
    tcr_neighbors
 
 
 Tools: `tl`
 -----------
 
+Tools add an interpretable annotation to the :class:`~anndata.AnnData` object
+which usually can be visualized by a corresponding plotting function. 
+
 .. module:: scirpy.tl
 
+Generic
+^^^^^^^
+.. autosummary::
+   :toctree: . 
+
+   group_abundance
+
+Quality control
+^^^^^^^^^^^^^^^
+.. autosummary::
+   :toctree: . 
+
+   chain_pairing
+
+Define and visualize clonotypes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 .. autosummary::
    :toctree: .
 
    define_clonotypes
    clonotype_network
-   chain_pairing
+
+Analyse clonal diversity
+^^^^^^^^^^^^^^^^^^^^^^^^
+.. autosummary::
+   :toctree: .
+
    clonal_expansion
    summarize_clonal_expansion
    alpha_diversity
-   group_abundance
-   spectratype
    repertoire_overlap
    clonotype_imbalance
 
+V(D)J gene usage
+^^^^^^^^^^^^^^^^
+.. autosummary::
+   :toctree: .
+
+   spectratype
+
+
 
 Plotting: `pl`
 --------------
 
 .. module:: scirpy.pl
 
+Generic
+^^^^^^^
+.. autosummary::
+   :toctree: . 
+
+   embedding
+
+
+Tools
+^^^^^
+Every of these plotting functions has a corresponding *tool* in the :mod:`scirpy.tl`
+section. Depending on the computational load, tools are either invoked on-the-fly
+when calling the plotting function or need to be precomputed and stored in 
+:class:`~anndata.AnnData` previously. 
+
 .. autosummary::
    :toctree: . 
 
@@ -78,7 +122,8 @@ Plotting: `pl`
    repertoire_overlap
    clonotype_imbalance
    clonotype_network
-   embedding
+   clonotype_network_igraph
+
 
 
 Base plotting functions: `pl.base`
@@ -107,6 +152,19 @@ Plot styling: `pl.styling`
    style_axes
 
 
+Datasets: `datasets`
+--------------------
+
+.. module:: scirpy.datasets
+
+.. autosummary::
+   :toctree: .
+
+   wu2020
+   wu2020_3k
+
+
+
 Utility functions: `util`
 -------------------------
 
@@ -115,4 +173,20 @@ Utility functions: `util`
 .. autosummary::
    :toctree: . 
 
-   graph.layout_components
+   graph.layout_components
+
+
+TCR distance metrics: `tcr_dist`
+-----------------------------------
+
+.. module:: scirpy.tcr_dist
+
+.. autosummary::
+   :toctree: .
+
+   tcr_dist
+   DistanceCalculator
+   IdentityDistanceCalculator
+   LevenshteinDistanceCalculator
+   AlignmentDistanceCalculator
+

docs/conf.py

@@ -21,6 +21,7 @@
 copyright = f"{datetime.now():%Y}, {author}."
 version = __version__
 
+templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"]
 
 
@@ -52,6 +53,8 @@
 napoleon_include_init_with_doc = False
 napoleon_use_rtype = True  # having a separate entry generally helps readability
 napoleon_use_param = True
+napoleon_use_ivar = True
+napoleon_custom_sections = [("Params", "Parameters")]
 todo_include_todos = False
 
 intersphinx_mapping = dict(
@@ -111,6 +114,10 @@ def setup(app):
 # -- Supress 'reference target not found' errors ---------------------------------------
 
 # See https://github.com/agronholm/sphinx-autodoc-typehints/issues/38 for more details.
-qualname_overrides = {}
+qualname_overrides = {"scipy.sparse.coo.coo_matrix": "scipy.sparse.coo_matrix"}
 
-nitpick_ignore = [("py:class", "igraph.Graph")]
+nitpick_ignore = [
+    ("py:class", "igraph.Graph"),
+    ("py:class", "igraph.Layout"),
+    ("py:class", "igraph.layout.Layout"),
+]