Improve directive arguments and behavior (#16)

Author: felix-hilden

docs/src/examples.rst

@@ -102,8 +102,6 @@ This was achieved with::
 Now all Python code blocks within the same section will be concatenated.
 See :ref:`reference` for more information on the exact behavior and options.
 
-.. concat-blocks:: reset
-
 Skipping blocks
 ---------------
 If needed, Python blocks can be skipped, resulting in no links for that block

docs/src/reference.rst

@@ -12,15 +12,6 @@ Configuration
 -------------
 Available configuration values in ``conf.py``:
 
-- :code:`codeautolink_concat_blocks: str`: Default behavior for code example
-  concatenation. Concatenated code blocks are treated as a continuous source,
-  so that imports and statements in previous blocks affect later blocks.
-  Value must be one of:
-
-  - "none" - no concatenation (default)
-  - "section" - blocks between titles
-  - "file" - all blocks in the current file
-
 - :code:`codeautolink_autodoc_inject: bool`: Inject a :code:`code-refs` table
   to the end of all autodoc definitions. Defaults to :code:`True`.
 
@@ -34,15 +25,17 @@ rST directives available in Sphinx documentation:
   ``type`` is "class" by default, which seems to work for other types as well.
   The table is removed if it would have no entries or a non-HTML builder is
   used.
-- :code:`.. concat-blocks:: level`: Toggle literal block concatenation.
+- :code:`.. concat-blocks:: [mode]`: Toggle literal block concatenation.
+  Concatenated code blocks are treated as a continuous source,
+  so that imports and statements in previous blocks affect later blocks.
   Concatenation is begun at the directive, not applied retroactively.
   The directive also resets concatenation state.
-  ``level`` must be one of:
+  ``mode``, if specified, must be one of:
 
-  - "none" - no concatenation
-  - "section" - blocks between titles
-  - "file" - all blocks in the current file
-  - "reset" - behavior reset to the value set in configuration
+  - "on" - concatenate all blocks in the current file (default value)
+  - "off" - no concatenation (default behavior until a :code:`concat-blocks`
+    directive is encountered)
+  - "section" - concatenate blocks until the next title
 
 - :code:`.. implicit-import:: code`: Include an implicit import in the next
   code block. The next block consumes this directive even if it is not
@@ -55,7 +48,7 @@ rST directives available in Sphinx documentation:
   - "next" - next block (default)
   - "section" - blocks until the next title
   - "file" - all blocks in the current file
-  - "none" - turn skipping off
+  - "off" - turn skipping off
 
   If "next" was specified, the following block consumes this directive even if
   it is not processed (e.g. non-Python blocks) to avoid placement confusion.

docs/src/release_notes.rst

@@ -10,6 +10,7 @@ sphinx-codeautolink adheres to
 
 Unreleased
 ----------
+- Improve directive arguments and behavior (:issue:`16`)
 - Correctly consume :code:`autolink-skip:: next` (:issue:`17`)
 
 0.1.1 (2021-09-22)

src/sphinx_codeautolink/extension/__init__.py

@@ -66,11 +66,7 @@ def parse_blocks(self, app, doctree):
         if self.do_nothing:
             return
 
-        visitor = CodeBlockAnalyser(
-            doctree,
-            concat_default=app.config.codeautolink_concat_blocks,
-            source_dir=app.srcdir,
-        )
+        visitor = CodeBlockAnalyser(doctree, source_dir=app.srcdir)
         doctree.walkabout(visitor)
         self.code_refs[visitor.current_document] = visitor.code_refs
         self.block_visitors.append(visitor)

src/sphinx_codeautolink/extension/block.py

@@ -33,7 +33,7 @@ class UserError(Exception):
 class CodeBlockAnalyser(nodes.SparseNodeVisitor):
     """Transform literal blocks of Python with links to reference documentation."""
 
-    def __init__(self, *args, concat_default: str, source_dir: str, **kwargs):
+    def __init__(self, *args, source_dir: str, **kwargs):
         super().__init__(*args, **kwargs)
         self.code_refs = {}
         relative_path = Path(self.document['source']).relative_to(source_dir)
@@ -42,26 +42,25 @@ def __init__(self, *args, concat_default: str, source_dir: str, **kwargs):
         self.current_refid = None
         self.source_transforms: List[SourceTransforms] = []
         self.implicit_imports = []
-        if concat_default not in ('none', 'section', 'file'):
-            raise UserError(
-                f'Invalid concatenation default value in "conf.py": `{concat_default}`'
-            )
-        self.concat_default = concat_default
-        self.concat_current = None
+        self.concat_global = 'off'
+        self.concat_section = False
         self.concat_sources = []
         self.autolink_skip = None
 
     def unknown_visit(self, node):
         """Handle and delete custom directives, ignore others."""
         if isinstance(node, ConcatBlocksMarker):
-            if node.level not in ('none', 'section', 'file', 'reset'):
+            if node.mode not in ('off', 'section', 'on'):
                 raise UserError(
-                    f'Invalid concatenation argument: `{node.level}` '
+                    f'Invalid concatenation argument: `{node.mode}` '
                     f'in document "{self.current_document}"'
                 )
 
             self.concat_sources = []
-            self.concat_current = node.level if node.level != 'reset' else None
+            if node.mode == 'section':
+                self.concat_section = True
+            else:
+                self.concat_global = node.mode
             node.parent.remove(node)
         elif isinstance(node, ImplicitImportMarker):
             if '\n' in node.content:
@@ -72,24 +71,22 @@ def unknown_visit(self, node):
             self.implicit_imports.append(node.content)
             node.parent.remove(node)
         elif isinstance(node, AutoLinkSkipMarker):
-            if node.level not in ('next', 'section', 'file', 'none'):
+            if node.level not in ('next', 'section', 'file', 'off'):
                 raise UserError(
                     f'Invalid skipping argument: `{node.level}` '
                     f'in document "{self.current_document}"'
                 )
-            self.autolink_skip = node.level if node.level != 'none' else None
+            self.autolink_skip = node.level if node.level != 'off' else None
             node.parent.remove(node)
 
-    def _concat_mode(self) -> str:
-        return self.concat_current or self.concat_default
-
     def unknown_departure(self, node):
         """Ignore unknown nodes."""
 
     def visit_title(self, node):
         """Track section names and break concatenation and skipping."""
         self.title_stack.append(node.astext())
-        if self._concat_mode() == 'section':
+        if self.concat_section:
+            self.concat_section = False
             self.concat_sources = []
         if self.autolink_skip == 'section':
             self.autolink_skip = None
@@ -142,7 +139,7 @@ def visit_literal_block(self, node: nodes.literal_block):
                 name.lineno -= hidden_len
                 name.end_lineno -= hidden_len
 
-        if self._concat_mode() != 'none':
+        if self.concat_section or self.concat_global == 'on':
             self.concat_sources.extend(implicit_imports + [source])
 
         transforms = SourceTransforms(source, [])

src/sphinx_codeautolink/extension/directive.py

@@ -45,13 +45,13 @@ def run(self):
 class ConcatBlocksMarker(nodes.Element):
     """Marker for :class:`ConcatBlocks` with attribute :attr:`level`."""
 
-    def __init__(self, level: str = None):
+    def __init__(self, mode: str = None):
         super().__init__()
-        self.level = level
+        self.mode = mode
 
     def copy(self):
         """Copy element."""
-        return self.__class__(self.level)
+        return self.__class__(self.mode)
 
 
 class ConcatBlocks(Directive):