[DOCS][FIX][RF] fix docstring formatting warning and refactor the apigen.py

docs/source/conf.py

@@ -40,12 +40,12 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "numpydoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.githubpages",
     "sphinx.ext.intersphinx",
     "sphinx.ext.mathjax",
     "sphinx.ext.viewcode",
-    "sphinx.ext.napoleon",
     "IPython.sphinxext.ipython_directive",
     "IPython.sphinxext.ipython_console_highlighting",
     "matplotlib.sphinxext.plot_directive",

docs/source/ext/apigen.py

@@ -38,7 +38,7 @@ class ApiDocWriter:
     def __init__(
         self,
         package_name,
-        rst_extension=".txt",
+        rst_extension=".rst",
         package_skip_patterns=None,
         module_skip_patterns=None,
         object_skip_patterns=None,
@@ -235,6 +235,7 @@ def _parse_module_with_import(self, uri):
 
         functions = []
         classes = []
+        constant_variables = []
         for n in node.body:
             if not hasattr(n, "name"):
                 if not isinstance(n, ast.Assign):
@@ -254,15 +255,15 @@ def _parse_module_with_import(self, uri):
                     if isinstance(n.value, ast.Call):
                         if isinstance(n.targets[0], ast.Tuple):
                             continue
-                        functions.append(n.targets[0].id)
+                        constant_variables.append(n.targets[0].id)
                     elif hasattr(n.value, "attr") and n.value.attr.startswith("vtk"):
                         classes.append(n.targets[0].id)
                 except Exception:
                     print(mod.__file__)
                     print(n.lineno)
                     print(n.targets[0])
 
-        return functions, classes
+        return functions, classes, constant_variables
 
     def _parse_lines(self, linesource):
         """Parse lines of text for functions and classes."""
@@ -302,7 +303,7 @@ def generate_api_doc(self, uri):
 
         """
         # get the names of all classes and functions
-        functions, classes = self._parse_module_with_import(uri)
+        functions, classes, constant_variables = self._parse_module_with_import(uri)
         if not len(functions) and not len(classes) and DEBUG:
             print("WARNING: Empty -", uri)  # dbg
 
@@ -323,8 +324,21 @@ def generate_api_doc(self, uri):
             head += title + "\n" + self.rst_section_levels[1] * len(title)
 
         head += "\n.. automodule:: " + uri + "\n"
+
         head += "\n.. currentmodule:: " + uri + "\n"
+
         body += "\n.. currentmodule:: " + uri + "\n\n"
+
+        for c in constant_variables:
+            # must NOT exclude from index to keep cross-refs working
+            body += c + "\n"
+            body += self.rst_section_levels[3] * len(c) + "\n"
+            body += "\n.. autodata:: " + c + "\n"
+            body += "   :no-value:\n"
+            body += "   :annotation:\n"
+
+            body += "\n\n"
+
         for c in classes:
             body += (
                 "\n:class:`"
@@ -335,23 +349,18 @@ def generate_api_doc(self, uri):
             )
             body += "\n.. autoclass:: " + c + "\n"
             # must NOT exclude from index to keep cross-refs working
-            body += (
-                "  :members:\n"
-                "  :undoc-members:\n"
-                "  :show-inheritance:\n"
-                "\n"
-                "  .. automethod:: __init__\n\n"
-            )
+            body += "  :members:\n" "  :undoc-members:\n" "  :show-inheritance:\n" "\n"
         head += ".. autosummary::\n\n"
-        for f in classes + functions:
+        for f in constant_variables + classes + functions:
             head += "   " + f + "\n"
-        head += "\n"
+        head += "\n\n"
 
         for f in functions:
             # must NOT exclude from index to keep cross-refs working
             body += f + "\n"
             body += self.rst_section_levels[3] * len(f) + "\n"
-            body += "\n.. autofunction:: " + f + "\n\n"
+            body += "\n.. autofunction:: " + f + "\n"
+            body += "\n\n"
 
         return head, body
 

fury/actors/peak.py

@@ -28,40 +28,54 @@ class PeakActor(Actor):
 
     Parameters
     ----------
+
     directions : ndarray
-        Peak directions. The shape of the array should be (X, Y, Z, D, 3).
+
+      Peak directions. The shape of the array should be (X, Y, Z, D, 3).
+
     indices : tuple
-        Indices given in tuple(x_indices, y_indices, z_indices)
-        format for mapping 2D ODF array to 3D voxel grid.
+
+      Indices given in tuple(x_indices, y_indices, z_indices)
+      format for mapping 2D ODF array to 3D voxel grid.
+
     values : ndarray, optional
-        Peak values. The shape of the array should be (X, Y, Z, D).
+
+      Peak values. The shape of the array should be (X, Y, Z, D).
+
     affine : array, optional
-        4x4 transformation array from native coordinates to world coordinates.
-    colors : None or string ('rgb_standard') or tuple (3D or 4D) or
-             array/ndarray (N, 3 or 4) or array/ndarray (K, 3 or 4) or
-             array/ndarray(N, ) or array/ndarray (K, )
-        If None a standard orientation colormap is used for every line.
-        If one tuple of color is used. Then all streamlines will have the same
-        color.
-        If an array (N, 3 or 4) is given, where N is equal to the number of
-        points. Then every point is colored with a different RGB(A) color.
-        If an array (K, 3 or 4) is given, where K is equal to the number of
-        lines. Then every line is colored with a different RGB(A) color.
-        If an array (N, ) is given, where N is the number of points then these
-        are considered as the values to be used by the colormap.
-        If an array (K,) is given, where K is the number of lines then these
-        are considered as the values to be used by the colormap.
+
+      4x4 transformation array from native coordinates to world coordinates.
+
+    colors : None or string ('rgb_standard') or tuple (3D or 4D) or array/ndarray (N, 3 or 4) or array/ndarray (K, 3 or 4) or array/ndarray(N, ) or array/ndarray (K, )
+
+      If None a standard orientation colormap is used for every line.
+      If one tuple of color is used. Then all streamlines will have the same
+      color.
+      If an array (N, 3 or 4) is given, where N is equal to the number of
+      points. Then every point is colored with a different RGB(A) color.
+      If an array (K, 3 or 4) is given, where K is equal to the number of
+      lines. Then every line is colored with a different RGB(A) color.
+      If an array (N, ) is given, where N is the number of points then these
+      are considered as the values to be used by the colormap.
+      If an array (K,) is given, where K is the number of lines then these
+      are considered as the values to be used by the colormap.
+
     lookup_colormap : vtkLookupTable, optional
-        Add a default lookup table to the colormap. Default is None which calls
-        :func:`fury.actor.colormap_lookup_table`.
+
+      Add a default lookup table to the colormap. Default is None which calls
+      :func:`fury.actor.colormap_lookup_table`.
+
     linewidth : float, optional
-        Line thickness. Default is 1.
+
+      Line thickness. Default is 1.
+
     symmetric: bool, optional
-        If True, peaks are drawn for both peaks_dirs and -peaks_dirs. Else,
-        peaks are only drawn for directions given by peaks_dirs. Default is
-        True.
 
-    """
+      If True, peaks are drawn for both peaks_dirs and -peaks_dirs. Else,
+      peaks are only drawn for directions given by peaks_dirs. Default is
+      True.
+
+    """  # noqa: E501
 
     @warn_on_args_to_kwargs()
     def __init__(

fury/actors/tensor.py

@@ -400,18 +400,22 @@ def main_dir_uncertainty(evals, evecs, signal, sigma, b_matrix):
     ----------
     evals : ndarray (3, ) or (N, 3)
         Eigenvalues.
+
     evecs : ndarray (3, 3) or (N, 3, 3)
         Eigenvectors.
+
     signal : 3D or 4D ndarray
         Predicted signal.
+
     sigma : ndarray
         Standard deviation of the noise.
+
     b_matrix : array (N, 7)
         Design matrix for DTI.
 
     Returns
     -------
-    angles: array
+    angles : array
 
     Notes
     -----
@@ -421,12 +425,12 @@ def main_dir_uncertainty(evals, evecs, signal, sigma, b_matrix):
     directly from estimated D and its estimated covariance matrix
     :math:`\\Delta D` (see [2]_, equation 4). The angle :math:`\\Theta`
     between the perturbed principal eigenvector of D,
-    :math:`\\epsilon_1+\\Delta\\epsilon_1`, and the estimated eigenvector
+    :math:`\\epsilon_1 + \\Delta\\epsilon_1`, and the estimated eigenvector
     :math:`\\epsilon_1`, measures the angular deviation of the main fiber
     direction and can be approximated by:
 
     .. math::
-        \\Theta=tan^{-1}(\\|\\Delta\\epsilon_1\\|)
+        \\Theta = tan^{-1}(\\|\\Delta \\ epsilon_1\\|)
 
     Giving way to a graphical construct for displaying both the main
     eigenvector of D and its associated uncertainty, with the so-called
@@ -435,13 +439,13 @@ def main_dir_uncertainty(evals, evecs, signal, sigma, b_matrix):
     References
     ----------
     .. [1] Basser, P. J. (1997). Quantifying errors in fiber direction and
-    diffusion tensor field maps resulting from MR noise. In 5th Scientific
-    Meeting of the ISMRM (Vol. 1740).
+        diffusion tensor field maps resulting from MR noise. In 5th Scientific
+        Meeting of the ISMRM (Vol. 1740).
 
     .. [2] Chang, L. C., Koay, C. G., Pierpaoli, C., & Basser, P. J. (2007).
-    Variance of estimated DTI-derived parameters via first-order perturbation
-    methods. Magnetic Resonance in Medicine: An Official Journal of the
-    International Society for Magnetic Resonance in Medicine, 57(1), 141-149.
+        Variance of estimated DTI-derived parameters via first-order perturbation
+        methods. Magnetic Resonance in Medicine: An Official Journal of the
+        International Society for Magnetic Resonance in Medicine, 57(1), 141-149.
 
     """
     angles = np.ones(evecs.shape[0])

fury/colormap.py

@@ -893,10 +893,14 @@ def get_xyz_coords(illuminant, observer):
     Notes
     -----
     Original Implementation from scikit-image package.
-    it can be found at:
+    it can be found here:
     https://github.com/scikit-image/scikit-image/blob/main/skimage/color/colorconv.py
     This implementation might have been modified.
 
+    References
+    ----------
+    .. [1] scikit-image, `colorconv.py` source code
+
     """
     illuminant = illuminant.upper()
     observer = observer.upper()

fury/gltf.py

@@ -1450,8 +1450,7 @@ def write_accessor(
     ----------
     gltf: GLTF2
         Pygltflib GLTF2 objecomp_type
-
-                      bufferview: int
+    bufferview: int
         BufferView Index
     byte_offset: int
         ByteOffset of the accessor
@@ -1467,6 +1466,7 @@ def write_accessor(
         Minimum elements of an array
 
     """
+
     accessor = gltflib.Accessor()
     accessor.bufferView = bufferview
     accessor.byteOffset = byte_offset

fury/lib.py

@@ -245,8 +245,7 @@
 UnstructuredGrid = cdmvtk.vtkUnstructuredGrid
 #: class for Polygon
 Polygon = cdmvtk.vtkPolygon
-#: class for DataObject
-DataObject = cdmvtk.vtkDataObject
+
 #: class for Molecule
 Molecule = cdmvtk.vtkMolecule
 #: class for DataSetAttributes

requirements/docs.txt

@@ -1,6 +1,7 @@
 # These are dependencies of various sphinx extensions for documentation.
 sphinx>=5.0.0
 ipython
+numpydoc
 matplotlib
 sphinx-copybutton
 sphinx-gallery>=0.10.0