order docdict alphabetically (#142)

pycrostates/utils/_docs.py

@@ -9,11 +9,11 @@
 
 from mne.utils.docs import docdict as docdict_mne
 
-# ------------------------- Documentation dictionary -------------------------
+# -- Documentation dictionary ----------------------------------------------------------
 docdict: dict[str, str] = {}
 
-# ---- Documentation to inc. from MNE ----
-keys: tuple[str, ...] = (
+# -- Documentation to inc. from MNE ----------------------------------------------------
+_KEYS_MNE: tuple[str, ...] = (
     "n_jobs",
     "picks_all",
     "random_state",
@@ -22,7 +22,7 @@
     "reject_by_annotation_raw",
 )
 
-for key in keys:
+for key in _KEYS_MNE:
     entry: str = docdict_mne[key]
     if ".. versionchanged::" in entry:
         entry = entry.replace(".. versionchanged::", ".. versionchanged:: MNE ")
@@ -31,105 +31,140 @@
     docdict[key] = entry
 del key
 
-docdict["verbose"] = """
-verbose : int | str | bool | None
-    Sets the verbosity level. The verbosity increases gradually between ``"CRITICAL"``,
-    ``"ERROR"``, ``"WARNING"``, ``"INFO"`` and ``"DEBUG"``. If None is provided, the
-    verbosity is set to ``"WARNING"``. If a bool is provided, the verbosity is set to
-    ``"WARNING"`` for False and to ``"INFO"`` for True."""
+# -- A ---------------------------------------------------------------------------------
+docdict["axes_cbar"] = """
+cbar_axes : Axes | None
+    Axes on which to draw the colorbar, otherwise the colormap takes space from the main
+    axes."""
 
-# ---- Clusters ----
-docdict["n_clusters"] = """
-n_clusters : int
-    The number of clusters, i.e. the number of microstates.
+docdict["axes_seg"] = """
+axes : Axes | None
+    Either ``None`` to create a new figure or axes on which the segmentation is
+    plotted."""
+
+docdict["axes_topo"] = """
+axes : Axes | None
+    Either ``None`` to create a new figure or axes (or an array of axes) on which the
+    topographic map should be plotted. If the number of microstates maps to plot is
+    ``≥ 1``, an array of axes of size ``n_clusters`` should be provided."""
+
+# -- B ---------------------------------------------------------------------------------
+docdict["block"] = """
+block : bool
+    Whether to halt program execution until the figure is closed."""
+
+# -- C ---------------------------------------------------------------------------------
+docdict["cluster"] = """
+cluster : :ref:`cluster`
+    Fitted clustering algorithm from which to compute score. For more details about
+    current clustering implementations, check the :ref:`Clustering` section of the
+    documentation.
 """
+
 docdict["cluster_centers"] = """
 cluster_centers : array (n_clusters, n_channels)
     Fitted clusters, i.e. the microstates maps."""
+
+docdict["cluster_centers_seg"] = """
+cluster_centers : array (n_clusters, n_channels)
+     Clusters, i.e. the microstates maps used to compute the segmentation."""
+
 docdict["cluster_names"] = """
 cluster_names : list | None
     Name of the clusters."""
 
-# ---- Metrics -----
-docdict["cluster"] = """
-cluster : :ref:`cluster`
-    Fitted clustering algorithm from which to compute score. For more details about
-    current clustering implementations, check the :ref:`Clustering` section of the
-    documentation.
-"""
+docdict["cmap"] = """
+cmap : str | colormap | None
+    The colormap to use. If None, ``viridis`` is used."""
 
-# ------ I/O -------
+# -- D ---------------------------------------------------------------------------------
+# -- E ---------------------------------------------------------------------------------
+# -- F ---------------------------------------------------------------------------------
 docdict["fname_fiff"] = """
 fname : str | Path
     Path to the ``.fif`` file where the clustering solution is saved."""
 
-# -- Segmentation --
-docdict["cluster_centers_seg"] = """
-cluster_centers : array (n_clusters, n_channels)
-     Clusters, i.e. the microstates maps used to compute the segmentation."""
-docdict["labels_raw"] = """
-labels : array of shape ``(n_samples,)``
-    Microstates labels attributed to each sample, i.e. the segmentation."""
+# -- G ---------------------------------------------------------------------------------
+# -- H ---------------------------------------------------------------------------------
+# -- I ---------------------------------------------------------------------------------
+docdict["ignore_repetitions"] = """
+ignore_repetitions : bool
+    If ``True``, ignores state repetitions.
+    For example, the input sequence ``AAABBCCD``
+    will be transformed into ``ABCD`` before any calculation.
+    This is equivalent to setting the duration of all states to 1 sample."""
+
+# -- J ---------------------------------------------------------------------------------
+# -- K ---------------------------------------------------------------------------------
+# -- L ---------------------------------------------------------------------------------
 docdict["labels_epo"] = """
 labels : array of shape ``(n_epochs, n_samples)``
     Microstates labels attributed to each sample, i.e. the segmentation."""
+
+docdict["labels_raw"] = """
+labels : array of shape ``(n_samples,)``
+    Microstates labels attributed to each sample, i.e. the segmentation."""
+
 docdict["labels_transition"] = """
 labels : array of shape ``(n_samples,)`` or ``(n_epochs, n_samples)``
     Microstates labels attributed to each sample, i.e. the segmentation."""
-# TODO: predict_parameters docstring is missing.
+
+# -- M ---------------------------------------------------------------------------------
+# -- N ---------------------------------------------------------------------------------
+docdict["n_clusters"] = """
+n_clusters : int
+    The number of clusters, i.e. the number of microstates.
+"""
+
+# -- O ---------------------------------------------------------------------------------
+# -- P ---------------------------------------------------------------------------------
 docdict["predict_parameters"] = """
 predict_parameters : dict | None
     The prediction parameters."""
-docdict["stat_transition"] = """
+
+# -- Q ---------------------------------------------------------------------------------
+# -- R ---------------------------------------------------------------------------------
+# -- S ---------------------------------------------------------------------------------
+docdict["stat_expected_transitions"] = """
 stat : str
     Aggregate statistic to compute transitions. Can be:
 
-    * ``count``: show the number of observations of each transition.
     * ``probability`` or ``proportion``: normalize count such as the probabilities along
       the first axis is always equal to ``1``.
     * ``percent``: normalize count such as the probabilities along the first axis is
       always equal to ``100``."""
-docdict["stat_expected_transitions"] = """
+
+docdict["stat_transition"] = """
 stat : str
     Aggregate statistic to compute transitions. Can be:
 
+    * ``count``: show the number of observations of each transition.
     * ``probability`` or ``proportion``: normalize count such as the probabilities along
       the first axis is always equal to ``1``.
     * ``percent``: normalize count such as the probabilities along the first axis is
       always equal to ``100``."""
-docdict["ignore_repetitions"] = """
-ignore_repetitions : bool
-    If ``True``, ignores state repetitions.
-    For example, the input sequence ``AAABBCCD``
-    will be transformed into ``ABCD`` before any calculation.
-    This is equivalent to setting the duration of all states to 1 sample."""
+
+# -- T ---------------------------------------------------------------------------------
 docdict["transition_matrix"] = """
 T : array of shape ``(n_cluster, n_cluster)``
     Array of transition probability values from one label to another.
     First axis indicates state ``"from"``. Second axis indicates state ``"to"``."""
 
-# ------ Viz -------
-docdict["cmap"] = """
-cmap : str | colormap | None
-    The colormap to use. If None, ``viridis`` is used."""
-docdict["block"] = """
-block : bool
-    Whether to halt program execution until the figure is closed."""
-docdict["axes_topo"] = """
-axes : Axes | None
-    Either ``None`` to create a new figure or axes (or an array of axes) on which the
-    topographic map should be plotted. If the number of microstates maps to plot is
-    ``≥ 1``, an array of axes of size ``n_clusters`` should be provided."""
-docdict["axes_seg"] = """
-axes : Axes | None
-    Either ``None`` to create a new figure or axes on which the segmentation is
-    plotted."""
-docdict["axes_cbar"] = """
-cbar_axes : Axes | None
-    Axes on which to draw the colorbar, otherwise the colormap takes space from the main
-    axes."""
+# -- U ---------------------------------------------------------------------------------
+# -- V ---------------------------------------------------------------------------------
+docdict["verbose"] = """
+verbose : int | str | bool | None
+    Sets the verbosity level. The verbosity increases gradually between ``"CRITICAL"``,
+    ``"ERROR"``, ``"WARNING"``, ``"INFO"`` and ``"DEBUG"``. If None is provided, the
+    verbosity is set to ``"WARNING"``. If a bool is provided, the verbosity is set to
+    ``"WARNING"`` for False and to ``"INFO"`` for True."""
+
+# -- W ---------------------------------------------------------------------------------
+# -- X ---------------------------------------------------------------------------------
+# -- Y ---------------------------------------------------------------------------------
+# -- Z ---------------------------------------------------------------------------------
 
-# ------------------------- Documentation functions --------------------------
+# -- Documentation functions -----------------------------------------------------------
 docdict_indented: dict[int, dict[str, str]] = {}
 
 

pycrostates/utils/tests/test_docs.py

@@ -1,8 +1,11 @@
 """Test _docs.py"""
 
+import re
+from pathlib import Path
+
 import pytest
 
-from pycrostates.utils._docs import copy_doc, fill_doc
+from pycrostates.utils._docs import _KEYS_MNE, copy_doc, docdict, fill_doc
 from pycrostates.utils._logs import verbose
 
 
@@ -207,3 +210,19 @@ def method4(verbose=None):
     assert foo.method1.__doc__ == foo2.method2.__doc__
     assert foo.method1.__doc__ == foo2.method3.__doc__
     assert foo.method1.__doc__ == foo2.method4.__doc__
+
+
+def test_docdict_order():
+    """Test that docdict is alphabetical."""
+    # read the file as text, and get entries via regex
+    docdict_ = docdict.copy()
+    for key in _KEYS_MNE:
+        del docdict_[key]
+    docs_path = Path(__file__).parents[1] / "_docs.py"
+    assert docs_path.is_file()
+    with open(docs_path, "r", encoding="UTF-8") as fid:
+        docs = fid.read()
+    entries = re.findall(r'docdict\[(?:\n    )?["\'](.+)["\']\n?\] = ', docs)
+    # test length, uniqueness and order
+    assert len(docdict_) == len(entries)
+    assert sorted(entries) == entries