ENH: Add support for gated exercise directives

Author: mmcky

sphinx_exercise/__init__.py

@@ -19,6 +19,8 @@
 
 from .directive import (
     ExerciseDirective,
+    ExerciseStartDirective,
+    ExerciseEndDirective,
     SolutionDirective,
     SolutionStartDirective,
     SolutionEndDirective,
@@ -30,11 +32,12 @@
     exercise_enumerable_node,
     visit_exercise_enumerable_node,
     depart_exercise_enumerable_node,
+    exercise_end_node,
     solution_node,
-    solution_start_node,
-    solution_end_node,
     visit_solution_node,
     depart_solution_node,
+    solution_start_node,
+    solution_end_node,
     is_extension_node,
     exercise_title,
     exercise_subtitle,
@@ -45,8 +48,9 @@
     depart_exercise_latex_number_reference,
 )
 from .transforms import (
-    CheckGatedSolutions,
+    CheckGatedDirectives,
     MergeGatedSolutions,
+    MergeGatedExercises,
 )
 from .post_transforms import (
     ResolveTitlesInExercises,
@@ -170,6 +174,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
 
     # Internal Title Nodes that don't need visit_ and depart_ methods
     # as they are resolved in post_transforms to docutil and sphinx nodes
+    app.add_node(exercise_end_node)
     app.add_node(solution_start_node)
     app.add_node(solution_end_node)
     app.add_node(exercise_title)
@@ -186,11 +191,14 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     )
 
     app.add_directive("exercise", ExerciseDirective)
+    app.add_directive("exercise-start", ExerciseStartDirective)
+    app.add_directive("exercise-end", ExerciseEndDirective)
     app.add_directive("solution", SolutionDirective)
     app.add_directive("solution-start", SolutionStartDirective)
     app.add_directive("solution-end", SolutionEndDirective)
 
-    app.add_transform(CheckGatedSolutions)
+    app.add_transform(CheckGatedDirectives)
+    app.add_transform(MergeGatedExercises)
     app.add_transform(MergeGatedSolutions)
 
     app.add_post_transform(UpdateReferencesToEnumerated)

sphinx_exercise/directive.py

@@ -16,6 +16,7 @@
 from .nodes import (
     exercise_node,
     exercise_enumerable_node,
+    exercise_end_node,
     solution_node,
     solution_start_node,
     solution_end_node,
@@ -105,6 +106,9 @@ def run(self) -> List[Node]:
         else:
             node = exercise_enumerable_node()
 
+        if self.name == "exercise-start":
+            node.gated = True
+
         # Parse custom subtitle option
         if self.arguments != []:
             subtitle = exercise_subtitle()
@@ -283,6 +287,74 @@ def run(self) -> List[Node]:
 # Gated Directives
 
 
+class ExerciseStartDirective(ExerciseDirective):
+    """
+    A gated directive for exercises
+
+    .. exercise:: <subtitle> (optional)
+       :label:
+       :class:
+       :nonumber:
+       :hidden:
+
+    This class is a child of ExerciseDirective so it supports
+    all the same options as the base exercise node
+    """
+
+    name = "exercise-start"
+
+    def run(self):
+        # Initialise Gated Registry
+        if not hasattr(self.env, "sphinx_exercise_gated_registry"):
+            self.env.sphinx_exercise_gated_registry = {}
+        gated_registry = self.env.sphinx_exercise_gated_registry
+        docname = self.env.docname
+        if docname not in gated_registry:
+            gated_registry[docname] = {
+                "start": [],
+                "end": [],
+                "sequence": [],
+                "msg": [],
+            }
+        gated_registry[self.env.docname]["start"].append(self.lineno)
+        gated_registry[self.env.docname]["sequence"].append("S")
+        gated_registry[self.env.docname]["msg"].append(
+            f"{self.name} at line: {self.lineno}"
+        )
+        # Run Parent Methods
+        return super().run()
+
+
+class ExerciseEndDirective(SphinxDirective):
+    """
+    A simple gated directive to mark end of an exercise
+
+    .. exercise-end::
+    """
+
+    name = "exercise-end"
+
+    def run(self):
+        # Initialise Gated Registry
+        if not hasattr(self.env, "sphinx_exercise_gated_registry"):
+            self.env.sphinx_exercise_gated_registry = {}
+        gated_registry = self.env.sphinx_exercise_gated_registry
+        docname = self.env.docname
+        if docname not in gated_registry:
+            gated_registry[docname] = {
+                "start": [],
+                "end": [],
+                "sequence": [],
+                "msg": [],
+            }
+        gated_registry[self.env.docname]["end"].append(self.lineno)
+        gated_registry[self.env.docname]["sequence"].append("E")
+        gated_registry[self.env.docname]["msg"].append(
+            f"{self.name} at line: {self.lineno}"
+        )
+        return [exercise_end_node()]
+
+
 class SolutionStartDirective(SolutionDirective):
     """
     A gated directive for solution

sphinx_exercise/nodes.py

@@ -23,13 +23,18 @@
 
 
 class exercise_node(docutil_nodes.Admonition, docutil_nodes.Element):
-    pass
+    gated = False
 
 
 class exercise_enumerable_node(docutil_nodes.Admonition, docutil_nodes.Element):
+    gated = False
     resolved_title = False
 
 
+class exercise_end_node(docutil_nodes.Admonition, docutil_nodes.Element):
+    pass
+
+
 class solution_node(docutil_nodes.Admonition, docutil_nodes.Element):
     resolved_title = False
 
@@ -39,7 +44,7 @@ class solution_start_node(docutil_nodes.Admonition, docutil_nodes.Element):
 
 
 class solution_end_node(docutil_nodes.Admonition, docutil_nodes.Element):
-    resolved_title = False
+    resolved_title = False  # TODO: is this required?
 
 
 class exercise_title(docutil_nodes.title):

sphinx_exercise/transforms.py

@@ -8,6 +8,9 @@
 # from sphinx.errors import ExtensionError
 
 from .nodes import (
+    exercise_node,
+    exercise_enumerable_node,
+    exercise_end_node,
     solution_node,
     solution_start_node,
     solution_end_node,
@@ -16,7 +19,7 @@
 logger = logging.getLogger(__name__)
 
 
-class CheckGatedSolutions(SphinxTransform):
+class CheckGatedDirectives(SphinxTransform):
     """
     This transform checks the structure of the gated solutions
     to flag any errors in input
@@ -117,3 +120,63 @@ def apply(self):
             # Clean up Parent Node including :solution-end:
             for child in parent.children[parent_start + 1 : parent_end + 1]:
                 parent.remove(child)
+
+
+class MergeGatedExercises(SphinxTransform):
+    """
+    Transform Gated Exercise Directives into single unified
+    Directives in the Sphinx Abstract Syntax Tree
+
+    Note: The CheckGatedDirectives Transform should ensure the
+    structure of the gated directives is correct before
+    this transform is run.
+    """
+
+    default_priority = 10
+
+    def find_nodes(self, label, node):
+        parent_node = node.parent
+        parent_start, parent_end = None, None
+        for idx1, child in enumerate(parent_node.children):
+            if isinstance(
+                child, (exercise_node, exercise_enumerable_node)
+            ) and label == child.get("label"):
+                parent_start = idx1
+                for idx2, child2 in enumerate(parent_node.children[parent_start:]):
+                    if isinstance(child2, exercise_end_node):
+                        parent_end = idx1 + idx2
+                        break
+                break
+        return parent_start, parent_end
+
+    def merge_nodes(self, node):
+        label = node.get("label")
+        parent_start, parent_end = self.find_nodes(label, node)
+        if not parent_end:
+            return
+        parent = node.parent
+        # Use Current Node and remove "-start" from class names and type
+        updated_classes = [
+            cls.replace("-start", "") for cls in node.attributes["classes"]
+        ]
+        node.attributes["classes"] = updated_classes
+        node.attributes["type"] = node.attributes["type"].replace("-start", "")
+        # Attach content to section
+        content = node.children[-1]
+        for child in parent.children[parent_start + 1 : parent_end]:
+            content += child
+        # Clean up Parent Node including :exercise-end:
+        for child in parent.children[parent_start + 1 : parent_end + 1]:
+            parent.remove(child)
+
+    def apply(self):
+        # Process all matching exercise and exercise-enumerable (gated=True)
+        # and exercise-end nodes
+        for node in self.document.traverse(exercise_node):
+            if node.gated:
+                self.merge_nodes(node)
+            node.gated = False
+        for node in self.document.traverse(exercise_enumerable_node):
+            if node.gated:
+                self.merge_nodes(node)
+            node.gated = False

tests/books/test-gateddirective/conf.py

@@ -35,7 +35,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ["build", "_build", "errors_[1,2,3]*"]
+exclude_patterns = ["build", "_build", "solution_errors_[1,2,3]*"]
 
 
 # -- Options for HTML output -------------------------------------------------

tests/books/test-gateddirective/exercise-gated.md

@@ -0,0 +1,39 @@
+---
+jupytext:
+  text_representation:
+    extension: .md
+    format_name: myst
+kernelspec:
+  display_name: Python 3
+  language: python
+  name: python3
+---
+
+# Gated Exercises
+
+Some Gated reference exercises
+
+```{exercise-start}
+:label: gated-exercise-1
+```
+
+Replicate this figure using matplotlib
+
+```{figure} sphx_glr_cohere_001_2_0x.png
+```
+
+```{exercise-end}
+```
+
+and another version with a title embedded
+
+
+```{exercise-start} Replicate Matplotlib Plot
+:label: gated-exercise-2
+```
+
+```{figure} sphx_glr_cohere_001_2_0x.png
+```
+
+```{exercise-end}
+```

tests/books/test-gateddirective/exercise.md

@@ -9,7 +9,7 @@ kernelspec:
   name: python3
 ---
 
-# Exercise
+# Non-Gated Exercises
 
 Some reference exercises
 

tests/books/test-gateddirective/index.md

@@ -16,5 +16,7 @@ kernelspec:
 :maxdepth: 1
 
 exercise
-solution
+solution-exercise
+exercise-gated
+solution-exercise-gated
 ```