Clean doc warnings (#1124)

* clean doc lints

CHANGELOG.rst

@@ -145,8 +145,8 @@ Version 2.3.1
 
 Version 2.3.0
 -------------
-- Introduce a new method to calculate partition asymmetry by Uylings. See docstring of
-  :func:`neurom.features.neuritefunc.partition_asymmetries`.
+- Introduce a new method to calculate partition asymmetry by Uylings.
+  See docstring of `neurom.features.neuritefunc.partition_asymmetries`.
 - Follow the same morphology validation rules as in MorphIO. See the :ref:`doc page<validation>`
   about it.
 - Remove the cli command ``neurom features`` that listed all possible features. Instead a proper
@@ -161,8 +161,7 @@ Version 2.2.1
 Version 2.2.0
 -------------
 - Don't force loading of neurons into memory for Population (#922). See new API of
-  :class:`Population<neurom.core.population.Population>` and
-  :func:`load_neurons<neurom.io.utils.load_neurons>`
+  :class:`Population<neurom.core.population.Population>` and `load_neurons<neurom.io.utils.load_neurons>`
 - Move ``total_length`` feature to from ``neuritefunc`` to ``neuronfunc``. Use ``neurite_lengths``
   feature for neurites
 - Include morphology filename extension into Neuron's name

doc/source/api.rst

@@ -38,6 +38,8 @@ API Documentation
    :nosignatures:
    :toctree: _neurom_build
 
+   neurom
+   neurom.get
    neurom.morphmath
    neurom.features
    neurom.features.population
@@ -53,6 +55,7 @@ API Documentation
    neurom.core.soma
    neurom.core.dataformat
    neurom.io.utils
+   neurom.view
    neurom.view.dendrogram
    neurom.view.matplotlib_utils
    neurom.view.matplotlib_impl

doc/source/conf.py

@@ -40,8 +40,6 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys
-import os
 import importlib.metadata
 
 VERSION = importlib.metadata.version('neurom')
@@ -63,6 +61,14 @@
     'sphinx.ext.doctest',
 ]
 
+nitpicky = True
+nitpick_ignore = [
+    ("py:class", "Path"),
+    ("py:class", "morphio.Morphology"),
+    ("py:class", "morphio.mut.Morphology"),
+    ("py:class", "morphio.Section"),
+    ("py:class", "morphio.Soma"),
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

doc/source/morph_stats.rst

@@ -86,8 +86,7 @@ Here, there are two feature categories,
 2. ``neuron``: these are morphometrics that can be applied to a whole morphology, e.g. the soma radius,
    the trunk radii, etc.
 
-Each category sub-item (section_lengths, soma_radius, etc) corresponds to a
-:py:func:`neurom.get` feature, and each one of its sub-items corresponds to a statistic aggregating
+Each category sub-item (section_lengths, soma_radius, etc) corresponds to a :py:func:`neurom.get` feature, and each one of its sub-items corresponds to a statistic aggregating
 function, e.g.
 
 * ``raw``: array of raw values
@@ -140,9 +139,9 @@ The new format:
 - requires to use ``sum`` instead of ``total`` statistic aggregating function.
 - allows to specify features arguments.
 
-For example, ``partition_asymmetry`` feature has additional arguments like ``method`` and
-``variant`` (see :py:func:`neurom.features.neurite.partition_asymmetries`). Before it wasn't
-possible to set them. Here is how you can set them now:
+For example, ``partition_asymmetry`` feature has additional arguments like ``method`` and ``variant``.
+Before it wasn't possible to set them.
+Here is how you can set them now:
 
 .. code-block:: yaml
 

doc/source/quickstart.rst

@@ -85,13 +85,13 @@ we apply a simple user defined function to the apical dendrites in a population:
 
     stuff = [x for x in nm.iter_neurites(pop, user_func, lambda n : n.type == nm.APICAL_DENDRITE)]
 
-View morphologies with :mod:`neurom.viewer`
+View morphologies with :mod:`neurom.view`
 -------------------------------------------
 
 There are also helper functions to  plot a morphology in 2 and 3 dimensions.
 
-:func:`neurom.viewer.draw` function allows the user to make two and three-dimensional
-plots of neurites, somata and morphologies. It also has a dendrogram morphology plotting mode.
+:func:`neurom.view` function allows the user to make two and three-dimensional plots of neurites, somata and morphologies.
+It also has a dendrogram morphology plotting mode.
 
 
 Extract morphometrics into JSON files

neurom/check/morphology_checks.py

@@ -98,8 +98,8 @@ def has_no_flat_neurites(morph, tol=0.1, method='ratio'):
     Arguments:
         morph(Morphology): The morphology object to test
         tol(float): tolerance
-        method(string): way of determining flatness, 'tolerance', 'ratio' \
-        as described in :meth:`neurom.check.morphtree.get_flat_neurites`
+        method(str): way of determining flatness, 'tolerance', 'ratio'
+            as described in :meth:`neurom.check.morphtree.get_flat_neurites`
 
     Returns:
         CheckResult with result
@@ -184,8 +184,7 @@ def has_no_jumps(morph, max_distance=30.0, axis='z'):
 
     Arguments:
         morph(Morphology): the morphology to test
-        max_distance(float): value above which consecutive z-values are
-        considered a jump
+        max_distance(float): value above which consecutive z-values are considered a jump
         axis(str): one of x/y/z, which axis to check for jumps
 
     Returns:
@@ -228,11 +227,11 @@ def has_no_fat_ends(morph, multiple_of_mean=2.0, final_point_count=5):
     Arguments:
         morph(Morphology): the morphology to test
         multiple_of_mean(float): how many times larger the final radius
-        has to be compared to the mean of the final points
+            has to be compared to the mean of the final points
         final_point_count(int): how many points to include in the mean
 
     Returns:
-        CheckResult with result list of ids of bad sections
+        CheckResult with a list of all ids of bad sections
 
     Note:
         A fat end is defined as a leaf segment whose last point is larger
@@ -321,14 +320,13 @@ def has_no_narrow_neurite_section(
 
     Arguments:
         morph(Morphology): the morphology to test
-        neurite_filter(callable): filter the neurites by this callable
+        neurite_filter(Callable): filter the neurites by this callable
         radius_threshold(float): radii below this are considered narro
         considered_section_min_length(float): sections with length below
-        this are not taken into account
+            this are not taken into account
 
     Returns:
-        CheckResult with result. `result.info` contains the narrow section ids and their
-        first point
+        CheckResult with result. `result.info` contains the narrow section ids and their first point
     """
     considered_sections = (
         sec

neurom/check/morphtree.py

@@ -68,7 +68,7 @@ def is_flat(neurite, tol, method='tolerance'):
     Args:
         neurite(Neurite): neurite to operate on
         tol(float): tolerance
-        method(string): the method of flatness estimation:
+        method(str): the method of flatness estimation:
             'tolerance' returns true if any extent of the tree is smaller
             than the given tolerance
             'ratio' returns true if the ratio of the smallest directions
@@ -196,7 +196,7 @@ def is_back_tracking(neurite):
         neurite(Neurite): neurite to operate on
 
     Returns:
-        True Under the following scenaria:
+        bool: True when;
             1. A segment endpoint falls back and overlaps with a previous segment's point
             2. The geometry of a segment overlaps with a previous one in the section
     """
@@ -270,7 +270,7 @@ def get_flat_neurites(morph, tol=0.1, method='ratio'):
     Args:
         morph(Morphology): morphology to operate on
         tol(float): the tolerance or the ratio
-        method(string): 'tolerance' or 'ratio' described in :meth:`is_flat`
+        method(str): 'tolerance' or 'ratio' described in :meth:`is_flat`
 
     Returns:
         Bool list corresponding to the flatness check for each neurite

neurom/core/population.py

@@ -64,7 +64,7 @@ def __init__(
         """Construct a morphology population.
 
         Arguments:
-            files (collections.abc.Sequence[str|Path|Morphology]): collection of morphology files or
+            files (Sequence[str|Morphology|Path]): collection of morphology files or
                 paths to them or instances of ``Morphology``.
             name (str): Optional name for this Population
             ignored_exceptions (tuple): NeuroM and MorphIO exceptions that you want to ignore when

neurom/core/types.py

@@ -184,8 +184,7 @@ def tree_type_checker(*ref):
     """Tree type checker functor.
 
     Args:
-        *ref(NeuriteType|tuple): Either a single NeuriteType or a variable list of them or a tuple
-        of them.
+        *ref(NeuriteType|tuple): Either a single NeuriteType, list of them or a tuple of them.
 
     Returns:
         Functor that takes a tree, and returns true if that tree matches any of

neurom/features/__init__.py

@@ -37,7 +37,6 @@
     >>> ax_sec_len = features.get('section_lengths', m, neurite_type=neurom.AXON)
 """
 
-import inspect
 import operator
 from enum import Enum
 from functools import partial, reduce, wraps
@@ -174,12 +173,12 @@ def get(feature_name, obj, **kwargs):
     For Population features see :mod:`neurom.features.population`.
 
     Arguments:
-        feature_name(string): feature to extract
+        feature_name(str): feature to extract
         obj: a morphology, a morphology population or a neurite tree
         kwargs: parameters to forward to underlying worker functions
 
     Returns:
-        List|Number: feature value as a list or a single number.
+        List|float: feature value as a list or a single number.
     """
     return _get_feature_value_and_func(feature_name, obj, **kwargs)[0]
 
@@ -214,8 +213,8 @@ def feature(shape, namespace: NameSpace, name=None):
 
     Arguments:
         shape(tuple): the expected shape of the feature values
-        namespace(string): a namespace, see :class:`NameSpace`
-        name(string): name of the feature, used to access the feature via `neurom.features.get()`.
+        namespace(str): a namespace, see :class:`NameSpace`
+        name(str): name of the feature, used to access the feature via `neurom.features.get()`.
     """
 
     def inner(func):

neurom/features/morphology.py

@@ -595,7 +595,7 @@ def sholl_crossings(morph, neurite_type=NeuriteType.all, center=None, radii=None
         morph(Morphology|list): morphology or a list of neurites
         neurite_type(NeuriteType): Type of neurite to use. By default ``NeuriteType.all`` is used.
         center(Point): center point, if None then soma center is taken
-        radii(iterable of floats): radii for which crossings will be counted,
+        radii: iterable of floats for which crossings will be counted,
             if None then soma radius is taken
 
     Returns:
@@ -658,8 +658,8 @@ def sholl_frequency(morph, neurite_type=NeuriteType.all, step_size=10, bins=None
         morph(Morphology): a morphology
         neurite_type(NeuriteType): which neurites to operate on
         step_size(float): step size between Sholl radii
-        bins(iterable of floats): custom binning to use for the Sholl radii. If None, it uses
-        intervals of step_size between min and max radii of ``morphologies``.
+        bins: iterable of floats defining custom binning to use for the Sholl radii.
+            If None, it uses intervals of step_size between min and max radii of ``morphologies``.
 
     Note:
         Given a morphology, the soma center is used for the concentric circles,

neurom/features/neurite.py

@@ -317,8 +317,7 @@ def partition_asymmetry(
 
     Variant: length is a different definition, as the absolute difference in
     downstream path lenghts, relative to the total neurite path length
-    Method: 'petilla' or 'uylings'. The former is default. The latter uses ``-2`` shift. See
-    :func:`neurom.features.bifurcationfunc.partition_asymmetry`
+    Method: 'petilla' or 'uylings'. The former is default. The latter uses ``-2`` shift.
     """
     if variant not in {'branch-order', 'length'}:
         raise ValueError(

neurom/features/population.py

@@ -63,8 +63,8 @@ def sholl_frequency(morphs, neurite_type=NeuriteType.all, step_size=10, bins=Non
         morphs(list|Population): list of morphologies or morphology population
         neurite_type(NeuriteType): which neurites to operate on
         step_size(float): step size between Sholl radii
-        bins(iterable of floats): custom binning to use for the Sholl radii. If None, it uses
-        intervals of step_size between min and max radii of ``morphs``.
+        bins(Iterable[float]): custom binning to use for the Sholl radii.
+            If None, it uses intervals of step_size between min and max radii of ``morphs``.
         use_subtrees (bool): Enable mixed subtree processing.
 
     Note:

neurom/morphmath.py

@@ -50,8 +50,7 @@ def vector(p1, p2):
     """Compute vector between two 3D points.
 
     Args:
-        p1, p2: indexable objects with
-        indices 0, 1, 2 corresponding to 3D cartesian coordinates.
+        p1, p2: indexable objects with indices 0, 1, 2 corresponding to 3D cartesian coordinates.
 
     Returns:
         3-vector from p1 - p2
@@ -120,7 +119,7 @@ def path_fraction_id_offset(points, fraction, relative_offset=False):
 
     Args:
         points: an iterable of indexable objects with indices
-        0, 1, 2 correspoding to 3D cartesian coordinates
+            0, 1, 2 correspoding to 3D cartesian coordinates
         fraction: path length fraction (0.0 <= fraction <= 1.0)
         relative_offset: return absolute or relative segment distance
 
@@ -149,7 +148,7 @@ def path_fraction_point(points, fraction):
 
     Args:
         points: an iterable of indexable objects with indices
-        0, 1, 2 correspoding to 3D cartesian coordinates
+            0, 1, 2 correspoding to 3D cartesian coordinates
         fraction: path length fraction (0 <= fraction <= 1)
 
     Returns:
@@ -163,8 +162,7 @@ def scalar_projection(v1, v2):
     """Compute the scalar projection of v1 upon v2.
 
     Args:
-        v1, v2: iterable
-        indices 0, 1, 2 corresponding to cartesian coordinates
+        v1, v2: iterable indices 0, 1, 2 corresponding to cartesian coordinates
 
     Returns:
         3-vector of the projection of point p onto the direction of v
@@ -176,8 +174,7 @@ def vector_projection(v1, v2):
     """Compute the vector projection of v1 upon v2.
 
     Args:
-        v1, v2: iterable
-        indices 0, 1, 2 corresponding to cartesian coordinates
+        v1, v2: iterable indices 0, 1, 2 corresponding to cartesian coordinates
 
     Returns:
         3-vector of the projection of point p onto the direction of v
@@ -206,8 +203,7 @@ def point_dist2(p1, p2):
     """Compute the square of the euclidian distance between two 3D points.
 
     Args:
-        p1, p2: indexable objects with
-        indices 0, 1, 2 corresponding to 3D cartesian coordinates.
+        p1, p2: indexable objects with indices 0, 1, 2 corresponding to 3D cartesian coordinates.
 
     Returns:
         The square of the euclidian distance between the points.
@@ -220,8 +216,7 @@ def point_dist(p1, p2):
     """Compute the euclidian distance between two 3D points.
 
     Args:
-        p1, p2: indexable objects with
-        indices 0, 1, 2 corresponding to 3D cartesian coordinates.
+        p1, p2: indexable objects with indices 0, 1, 2 corresponding to 3D cartesian coordinates.
 
     Returns:
         The euclidian distance between the points.
@@ -236,7 +231,7 @@ def angle_3points(p0, p1, p2):
 
     Args:
         p0, p1, p2:  indexable objects with
-        indices 0, 1, 2 corresponding to 3D cartesian coordinates.
+            indices 0, 1, 2 corresponding to 3D cartesian coordinates.
 
     Returns:
         Angle in radians between (p1-p0) and (p2-p0).
@@ -392,9 +387,8 @@ def segment_radial_dist(seg, pos):
 
     Arguments:
         seg: tree segment
-
-        pos: origin to which distances are measured. It must have at lease 3
-        components. The first 3 components are (x, y, z).
+        pos: origin to which distances are measured.
+            It must have at lease 3 components. The first 3 components are (x, y, z).
     """
     return point_dist(pos, np.divide(np.add(seg[0], seg[1]), 2.0))
 
@@ -475,10 +469,10 @@ def principal_direction_extent(points):
     directions of the covariance matrix of the points.
 
     Args:
-        points : a 2D numpy array of points with 2 or 3 columns for (x, y, z)
+        points: a 2D numpy array of points with 2 or 3 columns for (x, y, z)
 
     Returns:
-        extents : the extents for each of the eigenvectors of the cov matrix
+        the extents for each of the eigenvectors of the cov matrix
 
     Note:
         Direction extents are ordered from largest to smallest.