add test to order docdict alphabetically

mne_lsl/utils/_docs.py

@@ -9,11 +9,11 @@
 
 from mne.utils.docs import docdict as docdict_mne
 
-# ------------------------- Documentation dictionary -------------------------
+# -- Documentation dictionary ----------------------------------------------------------
 docdict: dict[str, str] = dict()
 
-# -------- Documentation to inc. from MNE -------
-keys: tuple[str, ...] = (
+# -- Documentation to inc. from MNE ----------------------------------------------------
+_KEYS_MNE: tuple[str, ...] = (
     "anonymize_info_notes",
     "daysback_anonymize_info",
     "keep_his_anonymize_info",
@@ -26,7 +26,7 @@
     "ref_channels",
 )
 
-for key in keys:
+for key in _KEYS_MNE:
     entry: str = docdict_mne[key]
     if ".. versionchanged::" in entry:
         entry = entry.replace(".. versionchanged::", ".. versionchanged:: MNE ")
@@ -35,7 +35,25 @@
     docdict[key] = entry
 del key
 
-# -----------------------------------------------
+# -- A ---------------------------------------------------------------------------------
+# -- B ---------------------------------------------------------------------------------
+# -- C ---------------------------------------------------------------------------------
+# -- D ---------------------------------------------------------------------------------
+# -- E ---------------------------------------------------------------------------------
+# -- F ---------------------------------------------------------------------------------
+# -- G ---------------------------------------------------------------------------------
+# -- H ---------------------------------------------------------------------------------
+# -- I ---------------------------------------------------------------------------------
+# -- J ---------------------------------------------------------------------------------
+# -- K ---------------------------------------------------------------------------------
+# -- L ---------------------------------------------------------------------------------
+# -- M ---------------------------------------------------------------------------------
+# -- N ---------------------------------------------------------------------------------
+# -- O ---------------------------------------------------------------------------------
+# -- P ---------------------------------------------------------------------------------
+# -- Q ---------------------------------------------------------------------------------
+# -- R ---------------------------------------------------------------------------------
+# -- S ---------------------------------------------------------------------------------
 docdict["stream_bufsize"] = """
 bufsize : float | int
     Size of the buffer keeping track of the data received from the stream. If
@@ -44,7 +62,9 @@
     If the stream sampling rate ``sfreq`` is irregular, ``bufsize`` is
     expressed in samples. The buffer will hold the last ``bufsize`` samples."""
 
-# -----------------------------------------------
+# -- T ---------------------------------------------------------------------------------
+# -- U ---------------------------------------------------------------------------------
+# -- V ---------------------------------------------------------------------------------
 docdict["verbose"] = """
 verbose : int | str | bool | None
     Sets the verbosity level. The verbosity increases gradually between
@@ -53,7 +73,12 @@
     If a bool is provided, the verbosity is set to ``"WARNING"`` for False and
     to ``"INFO"`` for True."""
 
-# ------------------------- Documentation functions --------------------------
+# -- W ---------------------------------------------------------------------------------
+# -- X ---------------------------------------------------------------------------------
+# -- Y ---------------------------------------------------------------------------------
+# -- Z ---------------------------------------------------------------------------------
+
+# -- Documentation functions -----------------------------------------------------------
 docdict_indented: dict[int, dict[str, str]] = dict()
 
 

mne_lsl/utils/tests/test_docs.py

@@ -1,8 +1,11 @@
 """Test _docs.py"""
 
+import re
+from pathlib import Path
+
 import pytest
 
-from mne_lsl.utils._docs import copy_doc, fill_doc
+from mne_lsl.utils._docs import _KEYS_MNE, copy_doc, docdict, fill_doc
 from mne_lsl.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