set recursive autodoc generation to include 'nodes' and 'edges' (#185)

* set recursive autodoc generation to include 'nodes' and 'edges' * Made it easier to link to docs, and to describe the `Group Concept` Co-authored-by: Mike Gevaert <michael.gevaert@epfl.ch>
BlueBrain · Feb 24, 2023 · 8f89527 · 8f89527
1 parent 6ff31aa
commit 8f89527
Show file tree

Hide file tree

Showing 5 changed files with 58 additions and 52 deletions.
diff --git a/bluepysnap/frame_report.py b/bluepysnap/frame_report.py
@@ -80,7 +80,7 @@ def get(self, group=None, t_start=None, t_stop=None):
         """Fetch data from the report.
 
         Args:
-            group (None/int/list/np.array/dict): Get frames filtered by group. See NodePopulation.
+            group (None/int/list/np.array/dict): Get frames filtered by :ref:`Group Concept`.
             t_start (float): Include only frames occurring at or after this time.
             t_stop (float): Include only frames occurring at or before this time.
 
@@ -130,7 +130,7 @@ def __init__(self, frame_report, group=None, t_start=None, t_stop=None):
 
         Args:
             frame_report (FrameReport): The FrameReport to filter.
-            group (None/int/list/np.array/dict): Get frames filtered by group. See NodePopulation.
+            group (None/int/list/np.array/dict): Get frames filtered by :ref:`Group Concept`.
             t_start (float): Include only frames occurring at or after this time.
             t_stop (float): Include only frames occurring at or before this time.
 
@@ -272,7 +272,7 @@ def filter(self, group=None, t_start=None, t_stop=None):
         from all the populations of a report.
 
         Args:
-            group (None/int/list/np.array/dict): Get frames filtered by group. See NodePopulation.
+            group (None/int/list/np.array/dict): Get frames filtered by :ref:`Group Concept`.
             t_start (float): Include only frames occurring at or after this time.
             t_stop (float): Include only frames occurring at or before this time.
 

diff --git a/bluepysnap/nodes/node_population.py b/bluepysnap/nodes/node_population.py
@@ -15,7 +15,48 @@
 # along with this library; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
-"""Node population access."""
+"""Node population access.
+
+Group Concept
+=============
+
+A `Group` is a flexible way to address a series of node IDs, it can take the form of:
+
+- ``int``, ``CircuitNodeId``: return a single node ID if it belongs to the circuit.
+- ``CircuitNodeIds`` return IDs of nodes from the node population in an array.
+- ``sequence``: return IDs of nodes in an array.
+- ``str``: return IDs of nodes in a node set.
+- ``mapping``: return IDs of nodes matching a properties filter.
+- ``None``: return all node IDs.
+
+If ``group`` is a ``sequence``, the order of results is preserved.
+Otherwise the result is sorted and contains no duplicates.
+
+Examples:
+    The available group parameter values:
+
+    >>> nodes.ids(group=None)  #  returns all IDs
+    >>> nodes.ids(group={})  #  returns all IDs
+    >>> nodes.ids(group=1)  #  returns the single ID if present in population
+    >>> #  returns the single ID if present in population and the circuit id population
+    >>> #  corresponds to nodes.name
+    >>> nodes.ids(group=CircuitNodeId('pop', 1))
+    >>> nodes.ids(group=[1,2,3])  # returns list of IDs if all present in population
+    >>> #  returns list of IDs if all present in population
+    >>> nodes.ids(group=CircuitNodeIds.from_dict({"pop": [0, 1,2]}))
+    >>> nodes.ids(group="node_set_name")  # returns list of IDs matching node set
+    >>> nodes.ids(group={ Node.LAYER: 2})  # returns list of IDs matching layer==2
+    >>> nodes.ids(group={ Node.LAYER: [2, 3]})  # returns list of IDs with layer in [2,3]
+    >>> nodes.ids(group={ Node.X: (0, 1)})  # returns list of IDs with 0 < x < 1
+    >>> # returns list of IDs matching one of the queries inside the 'or' list
+    >>> nodes.ids(group={'$or': [{ Node.LAYER: [2, 3]},
+    >>>                          { Node.X: (0, 1), Node.MTYPE: 'L1_SLAC' }]})
+    >>> # returns list of IDs matching all the queries inside the 'and' list
+    >>> nodes.ids(group={'$and': [{ Node.LAYER: [2, 3]},
+    >>>                           { Node.X: (0, 1), Node.MTYPE: 'L1_SLAC' }]})
+
+    See more examples in ``NodePopulation::get``
+"""
 import inspect
 from collections.abc import Mapping, Sequence
 from copy import deepcopy
@@ -272,19 +313,8 @@ def ids(self, group=None, limit=None, sample=None, raise_missing_property=True):
         """Node IDs corresponding to node ``group``.
 
         Args:
-            group (int/CircuitNodeId/CircuitNodeIds/sequence/str/mapping/None): Which IDs will be
-                returned depends on the type of the ``group`` argument:
-
-                - ``int``, ``CircuitNodeId``: return a single node ID if it belongs to the circuit.
-                - ``CircuitNodeIds`` return IDs of nodes from the node population in an array.
-                - ``sequence``: return IDs of nodes in an array.
-                - ``str``: return IDs of nodes in a node set.
-                - ``mapping``: return IDs of nodes matching a properties filter.
-                - ``None``: return all node IDs.
-
-                If ``group`` is a ``sequence``, the order of results is preserved.
-                Otherwise the result is sorted and contains no duplicates.
-
+            group (int/CircuitNodeId/CircuitNodeIds/sequence/str/mapping/None):
+                See :ref:`Group Concept`
             sample (int): If specified, randomly choose ``sample`` number of
                 IDs from the match result. If the size of the sample is greater than
                 the size of the NodePopulation then all ids are taken and shuffled.
@@ -298,29 +328,6 @@ def ids(self, group=None, limit=None, sample=None, raise_missing_property=True):
 
         Returns:
             numpy.array: A numpy array of IDs.
-
-        Examples:
-            The available group parameter values:
-
-            >>> nodes.ids(group=None)  #  returns all IDs
-            >>> nodes.ids(group={})  #  returns all IDs
-            >>> nodes.ids(group=1)  #  returns the single ID if present in population
-            >>> #  returns the single ID if present in population and the circuit id population
-            >>> #  corresponds to nodes.name
-            >>> nodes.ids(group=CircuitNodeId('pop', 1))
-            >>> nodes.ids(group=[1,2,3])  # returns list of IDs if all present in population
-            >>> #  returns list of IDs if all present in population
-            >>> nodes.ids(group=CircuitNodeIds.from_dict({"pop": [0, 1,2]}))
-            >>> nodes.ids(group="node_set_name")  # returns list of IDs matching node set
-            >>> nodes.ids(group={ Node.LAYER: 2})  # returns list of IDs matching layer==2
-            >>> nodes.ids(group={ Node.LAYER: [2, 3]})  # returns list of IDs with layer in [2,3]
-            >>> nodes.ids(group={ Node.X: (0, 1)})  # returns list of IDs with 0 < x < 1
-            >>> # returns list of IDs matching one of the queries inside the 'or' list
-            >>> nodes.ids(group={'$or': [{ Node.LAYER: [2, 3]},
-            >>>                          { Node.X: (0, 1), Node.MTYPE: 'L1_SLAC' }]})
-            >>> # returns list of IDs matching all the queries inside the 'and' list
-            >>> nodes.ids(group={'$and': [{ Node.LAYER: [2, 3]},
-            >>>                           { Node.X: (0, 1), Node.MTYPE: 'L1_SLAC' }]})
         """
         # pylint: disable=too-many-branches
         preserve_order = False
@@ -369,16 +376,8 @@ def get(self, group=None, properties=None):
         """Node properties as a pandas Series or DataFrame.
 
         Args:
-            group (int/CircuitNodeId/CircuitNodeIds/sequence/str/mapping/None): Which nodes will
-                have their properties returned depends on the type of the ``group`` argument:
-
-                - ``int``, ``CircuitNodeId``: return the properties of a single node.
-                - ``CircuitNodeIds`` return the properties from a NodeCircuitNodeIds.
-                - ``sequence``: return the properties from a list of node.
-                - ``str``: return the properties of nodes in a node set.
-                - ``mapping``: return the properties of nodes matching a properties filter.
-                - ``None``: return the properties of all nodes.
-
+            group (int/CircuitNodeId/CircuitNodeIds/sequence/str/mapping/None):
+                see :ref:`Group Concept`
             properties (list|str|None): If specified, return only the properties in the list.
                 Otherwise return all properties.
 

diff --git a/doc/source/circuits.rst b/doc/source/circuits.rst
@@ -5,6 +5,7 @@ Circuits
 
 .. autosummary::
    :toctree: submodules
+   :recursive:
 
    circuit
    config

diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -23,8 +23,10 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
-    "sphinx.ext.napoleon",
     "sphinx.ext.autosummary",
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -69,3 +71,7 @@
 
 # autosummary settings
 autosummary_generate = True
+
+suppress_warnings = [
+    "autosectionlabel.*",
+]
diff --git a/tox.ini b/tox.ini
@@ -50,7 +50,7 @@ extras = docs
 commands =
     make clean
     make html SPHINXOPTS=-W
-whitelist_externals = make
+allowlist_externals = make
 
 # E203: whitespace before ':'
 # E731: do not assign a lambda expression, use a def