added documentation of dispatch methods

in see also section

Signed-off-by: Nick Papior <[email protected]>

docs/api/basic.rst

@@ -66,6 +66,6 @@ In particular `oplist` is useful when calculating averages in Brillouin zones (s
 .. autosummary::
    :toctree: generated/
 
-   ~sisl.oplist.oplist
+   oplist
    ~sisl.utils.PropertyDict
 

docs/api/core.rst

@@ -0,0 +1,15 @@
+.. _core:
+
+**********
+Functional
+**********
+
+.. currentmodule:: sisl
+
+sisl provides simple functionality that may be used by various
+sisl objects.
+
+.. autosummary::
+   :toctree: generated/
+
+   tile

docs/api/index.rst

@@ -28,6 +28,7 @@ All methods and submodules are listed  :ref:`here <genindex>` and
    viz/index
    unit_constant
    utilities
+   core
 
 .. toctree::
    :maxdepth: 1

src/sisl/_ufuncs.py

@@ -3,6 +3,7 @@
 # file, You can obtain one at https://mozilla.org/MPL/2.0/.
 
 from functools import singledispatch, wraps
+from textwrap import dedent
 from typing import Callable, Optional
 
 from sisl.messages import SislError, warn
@@ -46,6 +47,21 @@ def decorator(func):
     return decorator
 
 
+def _append_doc_dispatch(method: Callable, cls: type):
+    """Append to the doc-string of the dispatch method retrieved by `method` that the `cls` class can be used"""
+    global _registry
+
+    # get method name
+    name = method.__name__
+
+    # retrieve dispatch method
+    method_registry = _registry[name]
+
+    # Append to doc string
+    doc = f"\n{cls.__name__}.{name}: when first argument is of type '{cls.__name__}'"
+    method_registry.__doc__ += doc
+
+
 def register_sisl_dispatch(
     module: Optional[str] = None, method: Optional[Callable] = None
 ):
@@ -65,9 +81,18 @@ def register_sisl_dispatch(
     if name not in _registry:
 
         def method_registry(*args, **kwargs):
-            f"""{name} dispatch method"""
+            """Dispatch method"""
             raise SislError
 
+        doc = dedent(
+            f"""\
+                Dispatcher for '{name}'
+
+                See also
+                --------
+                """
+        )
+        method_registry.__doc__ = doc
         method_registry.__name__ = name
         method_registry.__module__ = "sisl"
         _registry[name] = singledispatch(method_registry)
@@ -84,6 +109,7 @@ def method_registry(*args, **kwargs):
     new_registry = set(keys)
 
     for cls in new_registry - old_registry:
+        _append_doc_dispatch(method, cls)
         register_sisl_function(name, cls)(method)
 
     return method