Update documentation

- Add numpydoc for more consistency with their documentation and for docstring validation.
- Setup intersphinx (see pyt-team/TopoNetX#296).
- Fix documentation issues raised by numpydoc.

docs/conf.py

@@ -7,25 +7,18 @@
 extensions = [
     "nbsphinx",
     "nbsphinx_link",
+    "numpydoc",
     "sphinx.ext.autodoc",
     "sphinx.ext.coverage",
     "sphinx.ext.doctest",
     "sphinx.ext.githubpages",
+    "sphinx.ext.intersphinx",
     "sphinx.ext.mathjax",
-    "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
     "sphinx_gallery.load_style",
 ]
 
-# Configure napoleon for numpy docstring
-napoleon_google_docstring = False
-napoleon_numpy_docstring = True
-napoleon_use_param = False
-napoleon_use_ivar = False
-napoleon_use_rtype = False
-napoleon_include_init_with_doc = False
-
-# Configure nbsphinx for notebooks execution
+# Configure nbsphinx for notebook execution
 nbsphinx_execute_arguments = [
     "--InlineBackend.figure_formats={'svg', 'pdf'}",
     "--InlineBackend.rc={'figure.dpi': 96}",
@@ -45,7 +38,7 @@
 
 master_doc = "index"
 
-language = None
+language = "en"
 
 nbsphinx_prolog = r"""
 {% set docname = env.doc2path(env.docname, base=None) %}
@@ -93,3 +86,17 @@
 
 epub_title = project
 epub_exclude_files = ["search.html"]
+
+# configure intersphinx
+intersphinx_mapping = {
+    "networkx": ("https://networkx.org/documentation/stable/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "python": ("https://docs.python.org/3/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/", None),
+    "toponetx": ("https://pyt-team.github.io/toponetx/", None),
+}
+
+# configure numpydoc
+numpydoc_validation_checks = {"all", "GL01", "ES01", "SA01", "EX01"}
+numpydoc_show_class_members = False
+numpydoc_class_members_toctree = False

docs/contributing/index.rst

@@ -160,6 +160,8 @@ N.B. Within Notes, you can:
 - include LaTex code
 - cite references in text using ids placed in References
 
+.. _docstring-examples:
+
 Docstring Examples
 ~~~~~~~~~~~~~~~~~~
 

docs/index.rst

@@ -1,5 +1,5 @@
 🌐 TopoEmbedX (TEX) 🍩
-=====================
+=======================
 
 `TopoEmbedX` (TEX) is a Python package for representation Learning on Topological Domains. Topological domains are the natural mathematical structures representing relations between the components of a dataset.
 
@@ -8,7 +8,7 @@
    :class: with-shadow
    :width: 1000px
 
-Many natural systems as diverse as social networks and proteins are characterized by _relational structure_. This is the structure of interactions between components in the system, such as social interactions between individuals or electrostatic interactions between atoms. How can we conveniently represent data defined on such relational systems? `TopoEmbedX` (TEX) is a package for representation learning on topological domains, the mathematical structures of relational systems.
+Many natural systems as diverse as social networks and proteins are characterized by *relational structure*. This is the structure of interactions between components in the system, such as social interactions between individuals or electrostatic interactions between atoms. How can we conveniently represent data defined on such relational systems? `TopoEmbedX` (TEX) is a package for representation learning on topological domains, the mathematical structures of relational systems.
 
 
 🛠️ Main Features
@@ -30,7 +30,7 @@ To learn more about topological representation learning:
 
 - Mustafa Hajij, Ghada Zamzmi, Theodore Papamarkou, Nina Miolane, Aldo Guzmán-Sáenz, Karthikeyan Natesan Ramamurthy, Tolga Birdal, Tamal K. Dey, Soham Mukherjee, Shreyas N. Samaga, Neal Livesay, Robin Walters, Paul Rosen, Michael T. Schaub. `Topological Deep Learning: Going Beyond Graph Data <https://arxiv.org/abs/2206.00606>`__.
 
-.. code-block:: language
+.. code-block:: BibTeX
 
    @misc{hajij2023topological,
          title={Topological Deep Learning: Going Beyond Graph Data},
@@ -45,7 +45,7 @@ For a literature review of topological deep learning:
 
 - Mathilde Papillon, Sophia Sanborn, Mustafa Hajij, Nina Miolane. `Architectures of Topological Deep Learning: A Survey on Topological Neural Networks. <https://arxiv.org/pdf/2304.10031.pdf>`__
 
-.. code-block:: language
+.. code-block:: BibTeX
 
    @misc{papillon2023architectures,
          title={Architectures of Topological Deep Learning: A Survey on Topological Neural Networks},

topoembedx/classes/cell2vec.py

@@ -2,6 +2,7 @@
 
 import networkx as nx
 from karateclub import Node2Vec
+from toponetx.classes import Complex
 
 from topoembedx.neighborhood import neighborhood_from_complex
 
@@ -20,7 +21,6 @@ class Cell2Vec(Node2Vec):
     Additionally, users can specify the dimensions of the node embeddings to generate, the length and number of
     random walks to use for the node2vec algorithm, and the number of workers to use for parallelization.
 
-
     Parameters
     ----------
     walk_number : int, optional
@@ -80,15 +80,15 @@ def __init__(
 
     def fit(
         self,
-        complex,
+        complex: Complex,
         neighborhood_type="adj",
         neighborhood_dim={"rank": 0, "via_rank": -1},
-    ):
+    ) -> None:
         """Fit a Cell2Vec model.
 
         Parameters
         ----------
-        complex : TopoNetX object
+        complex : toponetx.classes.Complex
             A complex object. The complex object can be one of the following:
             - CellComplex
             - CombinatorialComplex
@@ -101,22 +101,18 @@ def fit(
             The integer parmaters needed to specify the neighborhood of the cells to generate the embedding.
             In TopoNetX  (co)adjacency neighborhood matrices are specified via one or two parameters.
             - For Cell/Simplicial/Path complexes (co)adjacency matrix is specified by a single parameter, this is precisely
-            neighborhood_dim["rank"]
+            neighborhood_dim["rank"].
             - For Combinatorial/ColoredHyperGraph the (co)adjacency matrix is specified by a single parameter, this is precisely
-            neighborhood_dim["rank"] and neighborhood_dim["via_rank"]
+            neighborhood_dim["rank"] and neighborhood_dim["via_rank"].
 
         Notes
         -----
-            Here neighborhood_dim={"rank": 1, "via_rank": -1} specifies the dimension for
-            which the cell embeddings are going to be computed.
-            "rank": 1 means that the embeddings will be computed for the first dimension.
-            The integer "via_rank": -1 is ignored when the input is cell/simplicial complex
-            and  must be specified when the input complex is a combinatorial complex or
-            colored hypergraph.
-
-        Returns
-        -------
-        None
+        Here neighborhood_dim={"rank": 1, "via_rank": -1} specifies the dimension for
+        which the cell embeddings are going to be computed.
+        "rank": 1 means that the embeddings will be computed for the first dimension.
+        The integer "via_rank": -1 is ignored when the input is cell/simplicial complex
+        and  must be specified when the input complex is a combinatorial complex or
+        colored hypergraph.
         """
         self.ind, self.A = neighborhood_from_complex(
             complex, neighborhood_type, neighborhood_dim

topoembedx/classes/cell_diff2vec.py

@@ -2,6 +2,7 @@
 
 import networkx as nx
 from karateclub import Diff2Vec
+from toponetx.classes.complex import Complex
 
 from topoembedx.neighborhood import neighborhood_from_complex
 
@@ -60,15 +61,15 @@ def __init__(
 
     def fit(
         self,
-        complex,
+        complex: Complex,
         neighborhood_type="adj",
         neighborhood_dim={"rank": 0, "via_rank": -1},
-    ):
+    ) -> None:
         """Fit a CellDiff2Vec model.
 
         Parameters
         ----------
-        complex : TopoNetX object
+        complex : toponetx.classes.Complex
             A complex object. The complex object can be one of the following:
             - CellComplex
             - CombinatorialComplex
@@ -81,22 +82,18 @@ def fit(
             The integer parmaters needed to specify the neighborhood of the cells to generate the embedding.
             In TopoNetX  (co)adjacency neighborhood matrices are specified via one or two parameters.
             - For Cell/Simplicial/Path complexes (co)adjacency matrix is specified by a single parameter, this is precisely
-            neighborhood_dim["rank"]
+            neighborhood_dim["rank"].
             - For Combinatorial/ColoredHyperGraph the (co)adjacency matrix is specified by a single parameter, this is precisely
-            neighborhood_dim["rank"] and neighborhood_dim["via_rank"]
+            neighborhood_dim["rank"] and neighborhood_dim["via_rank"].
 
         Notes
         -----
-            Here neighborhood_dim={"rank": 1, "via_rank": -1} specifies the dimension for
-            which the cell embeddings are going to be computed.
-            "rank": 1 means that the embeddings will be computed for the first dimension.
-            The integer "via_rank": -1 is ignored when the input is cell/simplicial complex
-            and  must be specified when the input complex is a combinatorial complex or
-            colored hypergraph.
-
-        Returns
-        -------
-        None
+        Here neighborhood_dim={"rank": 1, "via_rank": -1} specifies the dimension for
+        which the cell embeddings are going to be computed.
+        "rank": 1 means that the embeddings will be computed for the first dimension.
+        The integer "via_rank": -1 is ignored when the input is cell/simplicial complex
+        and  must be specified when the input complex is a combinatorial complex or
+        colored hypergraph.
         """
         self.ind, self.A = neighborhood_from_complex(
             complex, neighborhood_type, neighborhood_dim

topoembedx/classes/deepcell.py

@@ -2,6 +2,7 @@
 
 import networkx as nx
 from karateclub import DeepWalk
+from toponetx.classes import Complex
 
 from topoembedx.neighborhood import neighborhood_from_complex
 
@@ -60,15 +61,15 @@ def __init__(
 
     def fit(
         self,
-        complex,
+        complex: Complex,
         neighborhood_type="adj",
         neighborhood_dim={"rank": 0, "via_rank": -1},
-    ):
+    ) -> None:
         """Fit the model.
 
         Parameters
         ----------
-        complex : TopoNetX object
+        complex : toponetx.classes.Complex
             A complex object. The complex object can be one of the following:
             - CellComplex
             - CombinatorialComplex
@@ -81,22 +82,18 @@ def fit(
             The integer parmaters needed to specify the neighborhood of the cells to generate the embedding.
             In TopoNetX  (co)adjacency neighborhood matrices are specified via one or two parameters.
             - For Cell/Simplicial/Path complexes (co)adjacency matrix is specified by a single parameter, this is precisely
-            neighborhood_dim["rank"]
+            neighborhood_dim["rank"].
             - For Combinatorial/ColoredHyperGraph the (co)adjacency matrix is specified by a single parameter, this is precisely
-            neighborhood_dim["rank"] and neighborhood_dim["via_rank"]
+            neighborhood_dim["rank"] and neighborhood_dim["via_rank"].
 
         Notes
         -----
-            Here neighborhood_dim={"rank": 1, "via_rank": -1} specifies the dimension for
-            which the cell embeddings are going to be computed.
-            "rank": 1 means that the embeddings will be computed for the first dimension.
-            The integer "via_rank": -1 is ignored when the input is cell/simplicial complex
-            and  must be specified when the input complex is a combinatorial complex or
-            colored hypergraph.
-
-        Returns
-        -------
-        None
+        Here neighborhood_dim={"rank": 1, "via_rank": -1} specifies the dimension for
+        which the cell embeddings are going to be computed.
+        "rank": 1 means that the embeddings will be computed for the first dimension.
+        The integer "via_rank": -1 is ignored when the input is cell/simplicial complex
+        and  must be specified when the input complex is a combinatorial complex or
+        colored hypergraph.
         """
         self.ind, self.A = neighborhood_from_complex(
             complex, neighborhood_type, neighborhood_dim

topoembedx/classes/higher_order_laplacian_eigenmaps.py

@@ -1,8 +1,8 @@
 """Higher Order Laplacian Eigenmaps."""
 
 import networkx as nx
-import numpy as np
 from karateclub import LaplacianEigenmaps
+from toponetx.classes import Complex
 
 from topoembedx.neighborhood import neighborhood_from_complex
 
@@ -37,15 +37,15 @@ def __init__(
 
     def fit(
         self,
-        complex,
+        complex: Complex,
         neighborhood_type="adj",
         neighborhood_dim={"rank": 0, "via_rank": -1},
-    ):
+    ) -> None:
         """Fit a Higher Order Laplacian Eigenmaps model.
 
         Parameters
         ----------
-        complex : TopoNetX object
+        complex : toponetx.classes.Complex
             A complex object. The complex object can be one of the following:
             - CellComplex
             - CombinatorialComplex
@@ -58,22 +58,18 @@ def fit(
             The integer parmaters needed to specify the neighborhood of the cells to generate the embedding.
             In TopoNetX  (co)adjacency neighborhood matrices are specified via one or two parameters.
             - For Cell/Simplicial/Path complexes (co)adjacency matrix is specified by a single parameter, this is precisely
-            neighborhood_dim["rank"]
+            neighborhood_dim["rank"].
             - For Combinatorial/ColoredHyperGraph the (co)adjacency matrix is specified by a single parameter, this is precisely
-            neighborhood_dim["rank"] and neighborhood_dim["via_rank"]
+            neighborhood_dim["rank"] and neighborhood_dim["via_rank"].
 
         Notes
         -----
-            Here neighborhood_dim={"rank": 1, "via_rank": -1} specifies the dimension for
-            which the cell embeddings are going to be computed.
-            "rank": 1 means that the embeddings will be computed for the first dimension.
-            The integer "via_rank": -1 is ignored when the input is cell/simplicial complex
-            and  must be specified when the input complex is a combinatorial complex or
-            colored hypergraph.
-
-        Returns
-        -------
-        None
+        Here neighborhood_dim={"rank": 1, "via_rank": -1} specifies the dimension for
+        which the cell embeddings are going to be computed.
+        "rank": 1 means that the embeddings will be computed for the first dimension.
+        The integer "via_rank": -1 is ignored when the input is cell/simplicial complex
+        and  must be specified when the input complex is a combinatorial complex or
+        colored hypergraph.
         """
         self.ind, self.A = neighborhood_from_complex(
             complex, neighborhood_type, neighborhood_dim
@@ -88,8 +84,8 @@ def get_embedding(self, get_dict=False):
 
         Parameters
         ----------
-        get_dict : bool, optional
-            Return a dictionary of the embedding, by default False
+        get_dict : bool, default=False
+            Whether to return a dictionary of the embedding.
 
         Returns
         -------