Expand directive format validation

doc/sphinxext/directive_formatting.py

@@ -6,6 +6,57 @@
 
 from mne_doc_utils import sphinx_logger
 
+DIRECTIVE_NAMES = [
+    # Table of contents
+    "toctree",
+    # Admonitions, messages, warnings
+    "attention",
+    "caution",
+    "danger",
+    "error",
+    "hint",
+    "important",
+    "note",
+    "tip",
+    "warning",
+    "admonition",
+    "seealso",
+    # Changes between versions
+    "version-added",
+    "versionadded",
+    "versionchanged",
+    "version-changed",
+    "version-deprecated",
+    "deprecated",
+    "version-removed",
+    "versionremoved",
+    # Presentational
+    "rubric",
+    "centered",
+    "hlist",
+    # Code examples
+    "highlight",
+    "code-block",
+    "sourcecode",
+    "code",
+    "literalinclude",
+    # Glossary
+    "glossary",
+    # Meta-information
+    "sectionauthor",
+    "codeauthor",
+    # Index-generating markup
+    "index",
+    # Including content
+    "only",
+    # Tables
+    "tabularcolumns",
+    # Math
+    "math",
+    # Grammar production
+    "productionlist",
+]
+
 
 def setup(app):
     app.connect("source-read", check_directive_formatting)
@@ -19,7 +70,7 @@ def setup_module():
 
 
 def check_directive_formatting(*args):
-    """Check that directives are not missing a space.
+    """Check that directives are not malformed.
 
     For args, see Sphinx events 'source-read' and 'autodoc-process-docstring'.
     """
@@ -37,8 +88,8 @@ def check_directive_formatting(*args):
     else:
         raise RuntimeError("Unexpected number of arguments from Sphinx event")
 
-    # Check if any directives are present
-    if re.search(r"\.\.\s*[a-zA-Z]+::", source_concat) is None:
+    # Check if text resembling directives are present
+    if re.search(r"\.\.\s*[a-zA-Z\-]+\s*:", source_concat) is None:
         return
 
     # Separate content into lines (docstrings already are)
@@ -48,20 +99,34 @@ def check_directive_formatting(*args):
     # Check for bad formatting
     for idx, line in enumerate(source):
         # Check for missing space after '..'
-        missing = re.search(r"\.\.[a-zA-Z]+::", line)
+        missing = re.search(r"\.\.[a-zA-Z\-]+\s*:", line)
         if missing is not None:
             sphinx_logger.warning(
                 f"{source_type} '{name}' is missing a space after '..' in the "
                 f"directive '{missing.group()}'"
             )
         # Extra spaces after '..' don't affect formatting
 
+        # Check for bad number of final colons (should be exactly 2)
+        bad_colons = re.search(r"\.\.\s*[a-zA-Z\-]+\s*(?<!:)(:{3,}|:)(?!:)", line)
+        if bad_colons is not None:
+            # Strip out name
+            directive_name = re.sub(
+                r"\.\.\s*([a-zA-Z\-]+)\s*(?<!:)(:{3,}|:)(?!:)", r"\1", line
+            )
+            if directive_name in DIRECTIVE_NAMES:
+                sphinx_logger.warning(
+                    f"{source_type} '{name}' has bad number of final colons (i.e., not "
+                    f"2) in the directive '{bad_colons.group()}'"
+                )
+        # Space(s) between directive name and final colons don't affect formatting
+
         # Check for missing preceding blank line
         # (exceptions are for directives at the start of files, after a header, or after
         # another directive/another directive's content)
         if idx == 0:
             continue
-        dir_pattern = r"^\s*\.\. \w+::"  # line might start with whitespace
+        dir_pattern = r"^\s*\.\.\s*[a-zA-Z\-]+\s*::"  # line might start with whitespace
         head_pattern = r"^[-|=|\^]+$"
         directive = re.search(dir_pattern, line)
         if directive is not None:

mne/decoding/ems.py

@@ -60,7 +60,7 @@ def __repr__(self):  # noqa: D105
     def fit(self, X, y):
         """Fit the spatial filters.
 
-        .. note : EMS is fitted on data normalized by channel type before the
+        .. note:: EMS is fitted on data normalized by channel type before the
                   fitting of the spatial filters.
 
         Parameters
@@ -116,15 +116,15 @@ def compute_ems(
     gives the similarity between the filter at each time point and the
     data vector (sensors) at that time point.
 
-    .. note : EMS only works for binary classification.
+    .. note:: EMS only works for binary classification.
 
-    .. note : The present function applies a leave-one-out cross-validation,
+    .. note:: The present function applies a leave-one-out cross-validation,
               following Schurger et al's paper. However, we recommend using
               a stratified k-fold cross-validation. Indeed, leave-one-out tends
               to overfit and cannot be used to estimate the variance of the
               prediction within a given fold.
 
-    .. note : Because of the leave-one-out, this function needs an equal
+    .. note:: Because of the leave-one-out, this function needs an equal
               number of epochs in each of the two conditions.
 
     Parameters

mne/filter.py

@@ -2744,11 +2744,11 @@ def apply_hilbert(
         channels/vertices defined in ``picks`` is computed, resulting in the envelope
         signal.
 
-        .. warning: Do not use ``envelope=True`` if you intend to compute
-                    an inverse solution from the raw data. If you want to
-                    compute the envelope in source space, use
-                    ``envelope=False`` and compute the envelope after the
-                    inverse solution has been obtained.
+        .. warning::
+            Do not use ``envelope=True`` if you intend to compute an inverse solution
+            from the raw data. If you want to compute the envelope in source space, use
+            ``envelope=False`` and compute the envelope after the inverse solution has
+            been obtained.
 
         If ``envelope=False``, more memory is required since the original raw data
         as well as the analytic signal have temporarily to be stored in memory.

mne/morph.py

@@ -37,9 +37,7 @@
     verbose,
     warn,
 )
-from .utils import (
-    warn as warn_,
-)
+from .utils import warn as warn_
 
 
 @verbose
@@ -523,8 +521,8 @@ def apply(
         mri_resolution : bool | tuple | int | float
             If True the image is saved in MRI resolution. Default False.
 
-            .. warning: If you have many time points the file produced can be
-                        huge. The default is ``mri_resolution=False``.
+            .. warning:: If you have many time points the file produced can be
+                         huge. The default is ``mri_resolution=False``.
         mri_space : bool | None
             Whether the image to world registration should be in mri space. The
             default (None) is mri_space=mri_resolution.

mne/source_estimate.py

@@ -2546,8 +2546,8 @@ def save_as_volume(
         mri_resolution : bool
             It True the image is saved in MRI resolution.
 
-            .. warning: If you have many time points the file produced can be
-                        huge. The default is ``mri_resolution=False``.
+            .. warning:: If you have many time points the file produced can be
+                         huge. The default is ``mri_resolution=False``.
         format : str
             Either ``'nifti1'`` (default) or ``'nifti2'``.
 
@@ -2596,8 +2596,8 @@ def as_volume(
         mri_resolution : bool
             It True the image is saved in MRI resolution.
 
-            .. warning: If you have many time points the file produced can be
-                        huge. The default is ``mri_resolution=False``.
+            .. warning:: If you have many time points the file produced can be
+                         huge. The default is ``mri_resolution=False``.
         format : str
             Either 'nifti1' (default) or 'nifti2'.
 

tutorials/intro/70_report.py

@@ -46,12 +46,13 @@
 # You may also use the :meth:`~mne.Report.parse_folder` method to select
 # particular files to include in the report. But more on that later.
 #
-# .. sidebar: Viewing the report
+# .. sidebar:: Viewing the report
 #
 #    On successful creation of the report, the :meth:`~mne.Report.save` method
 #    will open the HTML in a new tab in your browser. To disable this, use the
 #    ``open_browser=False`` parameter of :meth:`~mne.Report.save`.
-#
+
+# %%
 # Adding `~mne.io.Raw` data
 # ^^^^^^^^^^^^^^^^^^^^^^^^^
 #