diff --git a/mne_lsl/utils/_docs.py b/mne_lsl/utils/_docs.py index 356a435c3..35a55bed6 100644 --- a/mne_lsl/utils/_docs.py +++ b/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() diff --git a/mne_lsl/utils/tests/test_docs.py b/mne_lsl/utils/tests/test_docs.py index 4d596f96f..619be9415 100644 --- a/mne_lsl/utils/tests/test_docs.py +++ b/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