directive matching enhancement and doc correction

Author: frantic1048

docs/conf.rst

@@ -15,12 +15,12 @@ The extension provides the following configuration:
                   - mock ``toctree`` directive in default mode
                   - mock ``contents`` directive in ``hide`` mode
 
-:mock_default_mode: (Type: ``str``, ''Default: ``'hide'``)
+:mock_default_mode: (Type: ``str``, Default: ``'hide'``)
 
                     The default mode for mocking a directive/role.
                     Available values:
 
                     :hide: Hide the directive, it will not be seen on the document.
-                    :literal_block: Show the raw text of directive in a `literal block`__
+                    :literal: Show the raw text of directive in a `literal block`__
 
 __ https://docutils.sourceforge.io/docs/user/rst/quickref.html#literal-blocks

src/sphinxnotes/mock/__init__.py

@@ -3,7 +3,7 @@
 
 from sphinx.util import logging
 from sphinx.application import Sphinx
-from sphinx.config import Config
+from sphinx.config import Config, ENUM
 from sphinx.util.docutils import SphinxDirective
 
 from docutils.parsers.rst import directives
@@ -24,43 +24,59 @@ def __getitem__(self, _):
         return directives.unchanged
 
 
-class MockDirective(SphinxDirective):
-    optional_arguments = 1
-    final_argument_whitespace = True
-    option_spec = MockOptionSpec()
-    has_content = True
+def _make_mock_directive(mode: str):
+    """Factory function to create a MockDirective class with pre-configured mode."""
 
-    def run(self) -> List[nodes.Node]:
-        mode = None
-        for d in self.config.mock_directives:
-            name = d if isinstance(d, str) else d[0]
-            if self.name != name:
-                continue
-            mode = self.config.mock_default_mode if isinstance(d, str) else d[1]
-            break
+    class MockDirective(SphinxDirective):
+        optional_arguments = 1
+        final_argument_whitespace = True
+        option_spec = MockOptionSpec()
+        has_content = True
 
-        if mode == 'literal':
-            literal = nodes.literal_block(self.block_text, self.block_text)
-            literal['language'] = 'rst'
-            return [literal]
-        elif mode == 'hide':
-            return []
-        else:
-            raise ValueError('unsupported mock mode')
+        def run(self) -> List[nodes.Node]:
+            if mode == 'literal':
+                literal = nodes.literal_block(self.block_text, self.block_text)
+                literal['language'] = 'rst'
+                return [literal]
+            else:  # mode == 'hide' (validated in _config_inited)
+                return []
 
+    return MockDirective
 
 
 def _config_inited(app:Sphinx, config:Config) -> None:
     for d in config.mock_directives:
         name = d if isinstance(d, str) else d[0]
-        app.add_directive(name, MockDirective, override=True)
+        mode = config.mock_default_mode if isinstance(d, str) else d[1]
+
+        if mode not in ('literal', 'hide'):
+            raise ValueError(
+                f'Invalid mock mode for directive "{name}": {mode!r}. '
+                f'Must be "literal" or "hide"'
+            )
+
+        directive_class = _make_mock_directive(mode)
+        app.add_directive(name, directive_class, override=True)
 
 
 def setup(app:Sphinx) -> Dict:
     """Sphinx extension entrypoint."""
 
-    app.add_config_value('mock_directives', [], 'env')
-    app.add_config_value('mock_default_mode', 'hide', 'env')
+    app.add_config_value(
+        'mock_directives',
+        default=[],
+        rebuild='env',
+        types=[list],
+        description='List of directive names to mock. Each item can be a string (directive name) '
+                    'or a tuple (directive name, mode).'
+    )
+    app.add_config_value(
+        'mock_default_mode',
+        default='hide',
+        rebuild='env',
+        types=ENUM('hide', 'literal'),
+        description='Default mode for mocking directives. Valid values: "hide", "literal".'
+    )
     app.connect('config-inited', _config_inited)
 
     return {'version': __version__}