Documentation (#5)

Add docstrings

---------

Co-authored-by: Lisandro Dalcin <dalcinl@gmail.com>

Author: mrogowski

docs/conf.py

@@ -71,6 +71,7 @@ def pkg_version():
 
 autodoc_preserve_defaults = True
 autodoc_typehints = 'description'
+autodoc_typehints_format = 'short'
 autodoc_type_aliases = {}
 autodoc_mock_imports = []
 
@@ -83,7 +84,6 @@ def pkg_version():
 napoleon_preprocess_types = True
 
 _numpy_types = [
-    'NDArray',
     'DTypeLike',
     'ArrayLike',
 ]
@@ -97,15 +97,10 @@ def pkg_version():
 ]
 
 autodoc_type_aliases.update({
-    typename: f'numpy.typing.{typename}'
+    typename: f'~numpy.typing.{typename}'
     for typename in _numpy_types
 })
 
-autodoc_type_aliases.update({
-    typename: f'{typename}'
-    for typename in _shmem_types
-})
-
 try:
     import sphinx_rtd_theme
     if 'sphinx_rtd_theme' not in extensions:
@@ -114,56 +109,74 @@ def pkg_version():
     sphinx_rtd_theme = None
 
 
-def _patch_util_inspect():
-    from sphinx.util.inspect import TypeAliasForwardRef
-    TypeAliasForwardRef.__getitem__ = lambda self, item: item
+def _patch_domain_python():
+    from sphinx.domains.python import PythonDomain
+    PythonDomain.object_types['data'].roles += ('class',)
 
 
-def _patch_domain_python():
-    from sphinx.domains import python
-
-    xref_info = {}
-    for typename in _numpy_types:
-        xref_info[f'numpy.typing.{typename}'] = {'reftype': 'data'}
-    for typename in _shmem_types:
-        xref_info[f'{typename}'] = {'reftype': 'data'}
-
-    def make_xref(self, rolename, domain, target, *args, **kwargs):
-        if target in ('None', 'True', 'False'):
-            rolename = 'obj'
-        pymodule = None
-        reftype = None
-        if target in xref_info:
-            reftype = xref_info[target].get('reftype')
-            pymodule, _, target  = target.rpartition('.')
-        xref = make_xref_orig(self, rolename, domain, target, *args, *kwargs)
-        if pymodule:
-            xref.attributes['py:module'] = pymodule
-        if reftype:
-            xref.attributes['reftype'] = reftype
-        return xref
-
-    make_xref_orig = python.PyXrefMixin.make_xref
-    python.PyXrefMixin.make_xref = make_xref
+def _patch_numpy_typing():
+    import numpy.typing
+    from types import new_class
+    from typing import Generic, TypeVar
+    NDArray = new_class('NDArray', (Generic[TypeVar('T')],))
+    NDArray.__module__ = numpy.typing.__name__
+    numpy.typing.NDArray = NDArray
+
+
+def _patch_cffi_typing():
+    from types import new_class
+    CData = new_class('CData')
+    CData.__module__ = 'ffi'
+    CData.__qualname__ = 'CData'
+    from shmem4py import shmem
+    for attr in _shmem_types:
+        data = getattr(shmem, attr)
+        if isinstance(data, typing.NewType):
+            if data.__supertype__ == shmem.ffi.CData:
+                data.__supertype__ = CData
+
+
+def _setup_autodoc(app):
+    from sphinx.ext import autodoc
+    from sphinx.ext import autosummary
+    from sphinx.util import inspect
+    from sphinx.util import typing
+    from sphinx.locale import _
+
+    #
+
+    def stringify_annotation(annotation, mode='fully-qualified-except-typing'):
+        qualname = getattr(annotation, '__qualname__', '')
+        module = getattr(annotation, '__module__', '')
+        args = getattr(annotation, '__args__', None)
+        if module == 'builtins' and qualname and args is not None:
+            args = ', '.join(stringify_annotation(a, mode) for a in args)
+            return f'{qualname}[{args}]'
+        return stringify_annotation_orig(annotation, mode)
+
+    try:
+        stringify_annotation_orig = typing.stringify_annotation
+        inspect.stringify_annotation = stringify_annotation
+        typing.stringify_annotation = stringify_annotation
+        autodoc.stringify_annotation = stringify_annotation
+        autodoc.typehints.stringify_annotation = stringify_annotation
+    except AttributeError:
+        stringify_annotation_orig = typing.stringify
+        inspect.stringify_annotation = stringify_annotation
+        typing.stringify = stringify_annotation
+        autodoc.stringify_typehint = stringify_annotation
 
 
 def setup(app):
-    _patch_util_inspect()
     _patch_domain_python()
+    _setup_autodoc(app)
 
+    _patch_numpy_typing()
     import numpy.typing
     typing.TYPE_CHECKING = True
     import shmem4py.shmem
     typing.TYPE_CHECKING = False
-
-    class CData: pass
-    CData.__module__ = 'ffi'
-    CData.__qualname__ = 'CData'
-    for attr in _shmem_types:
-        data = getattr(shmem4py.shmem, attr)
-        if isinstance(data, typing.NewType):
-            if data.__supertype__ == shmem4py.shmem.ffi.CData:
-                data.__supertype__ = CData
+    _patch_cffi_typing()
 
 
 # -- Options for HTML output -------------------------------------------------

docs/shmem.rst

@@ -22,20 +22,21 @@ Library Setup and Exit
    init
    finalize
    global_exit
-   THREAD
    init_thread
    query_thread
+   THREAD
 
 .. autofunction:: init
 .. autofunction:: finalize
 .. autofunction:: global_exit
-.. autoclass::    THREAD
 .. autofunction:: init_thread
 .. autofunction:: query_thread
 
+.. autoclass::    THREAD
 
-Accesibility Queries
---------------------
+
+Accessibility Queries
+---------------------
 
 .. autosummary::
    my_pe
@@ -65,6 +66,8 @@ Memory Management
    zeros
    ones
    full
+   MALLOC
+
 
 .. autofunction:: alloc
 .. autofunction:: free
@@ -77,15 +80,53 @@ Memory Management
 .. autofunction:: ones
 .. autofunction:: full
 
+.. autoclass:: MALLOC
+
+Team Management
+---------------
+.. autosummary::
+   Team
+   Team.destroy
+   Team.split_strided
+   Team.get_config
+   Team.my_pe
+   Team.n_pes
+   Team.translate_pe
+   Team.create_ctx
+   Team.sync
+
+.. autoclass:: Team
+
+   .. automethod:: destroy
+   .. automethod:: split_strided
+   .. automethod:: get_config
+   .. automethod:: my_pe
+   .. automethod:: n_pes
+   .. automethod:: translate_pe
+   .. automethod:: create_ctx
+   .. automethod:: sync
 
 Communication Management
 ------------------------
 
 .. autosummary::
    Ctx
+   Ctx.create
+   Ctx.destroy
+   Ctx.get_team
+   Ctx.fence
+   Ctx.quiet
+   CTX
 
 .. autoclass:: Ctx
 
+   .. automethod:: create
+   .. automethod:: destroy
+   .. automethod:: get_team
+   .. automethod:: fence
+   .. automethod:: quiet
+
+.. autoclass:: CTX
 
 Remote Memory Access
 --------------------
@@ -109,6 +150,12 @@ Remote Memory Access
 Atomic Memory Operations
 ------------------------
 
+.. autosummary::
+   atomic_op
+   atomic_fetch_op
+   atomic_fetch_op_nbi
+   AMO
+
 .. autosummary::
    atomic_set
    atomic_inc
@@ -134,10 +181,10 @@ Atomic Memory Operations
    atomic_fetch_or_nbi
    atomic_fetch_xor_nbi
 
-   AMO
-   atomic_op
-   atomic_fetch_op
-   atomic_fetch_op_nbi
+.. autofunction:: atomic_op
+.. autofunction:: atomic_fetch_op
+.. autofunction:: atomic_fetch_op_nbi
+.. autoclass::    AMO
 
 .. autofunction:: atomic_set
 .. autofunction:: atomic_inc
@@ -163,10 +210,6 @@ Atomic Memory Operations
 .. autofunction:: atomic_fetch_or_nbi
 .. autofunction:: atomic_fetch_xor_nbi
 
-.. autoclass::    AMO
-.. autofunction:: atomic_op
-.. autofunction:: atomic_fetch_op
-.. autofunction:: atomic_fetch_op_nbi
 
 
 Signaling Operations
@@ -176,24 +219,22 @@ Signaling Operations
    new_signal
    del_signal
    signal_fetch
-   SIGNAL
    put_signal
    put_signal_nbi
+   SIGNAL
 
 .. autofunction:: new_signal
 .. autofunction:: del_signal
 .. autofunction:: signal_fetch
-.. autoclass::    SIGNAL
 .. autofunction:: put_signal
 .. autofunction:: put_signal_nbi
+.. autoclass::    SIGNAL
 
 
 Collective Operations
 ---------------------
 
 .. autosummary::
-   Team
-
    barrier_all
    sync_all
    sync
@@ -204,8 +245,8 @@ Collective Operations
    alltoall
    alltoalls
 
-   OP
    reduce
+   OP
    and_reduce
    or_reduce
    xor_reduce
@@ -214,9 +255,6 @@ Collective Operations
    sum_reduce
    prod_reduce
 
-
-.. autoclass::    Team
-
 .. autofunction:: barrier_all
 .. autofunction:: sync_all
 
@@ -227,8 +265,8 @@ Collective Operations
 .. autofunction:: alltoall
 .. autofunction:: alltoalls
 
-.. autoclass::    OP
 .. autofunction:: reduce
+.. autoclass::    OP
 .. autofunction:: and_reduce
 .. autofunction:: or_reduce
 .. autofunction:: xor_reduce
@@ -242,7 +280,6 @@ Point-To-Point Synchronization
 ------------------------------
 
 .. autosummary::
-   CMP
    wait_until
    wait_until_all
    wait_until_any
@@ -257,8 +294,9 @@ Point-To-Point Synchronization
    test_all_vector
    test_any_vector
    test_some_vector
+   signal_wait_until
+   CMP
 
-.. autoclass::    CMP
 .. autofunction:: wait_until
 .. autofunction:: wait_until_all
 .. autofunction:: wait_until_any
@@ -273,6 +311,8 @@ Point-To-Point Synchronization
 .. autofunction:: test_all_vector
 .. autofunction:: test_any_vector
 .. autofunction:: test_some_vector
+.. autofunction:: signal_wait_until
+.. autoclass::    CMP
 
 
 Memory Ordering
@@ -302,6 +342,20 @@ Distributed Locking
 .. autofunction:: test_lock
 .. autofunction:: clear_lock
 
+Distributed Locking (Object-Oriented)
+-------------------------------------
+.. autosummary::
+   Lock
+   Lock.destroy
+   Lock.acquire
+   Lock.release
+
+.. autoclass:: Lock
+
+   .. automethod:: destroy
+   .. automethod:: acquire
+   .. automethod:: release
+
 
 Profiling Control
 -----------------