final code review

Author: mmcky

sphinx_exercise/__init__.py

@@ -1,12 +1,12 @@
 # -*- coding: utf-8 -*-
 """
-    sphinx_exercise
-    ~~~~~~~~~~~~~~~
-    This package is a namespace package that contains all extensions
-    distributed in the ``sphinx-contrib`` distribution.
-    :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
+sphinx_exercise
+~~~~~~~~~~~~~~~
+This package is an extension for sphinx to support exercise and solutions.
+:copyright: Copyright 2020-2021 by the Executable Books team, see AUTHORS.
+:license: MIT, see LICENSE for details.
 """
+
 from pathlib import Path
 from typing import Any, Dict, Set, Union, cast
 from sphinx.config import Config
@@ -20,27 +20,19 @@
 from .directive import ExerciseDirective, SolutionDirective
 from .nodes import (
     exercise_node,
-    exercise_enumerable_node,
-    solution_node,
     visit_exercise_node,
     depart_exercise_node,
+    exercise_enumerable_node,
     visit_exercise_enumerable_node,
     depart_exercise_enumerable_node,
+    solution_node,
     visit_solution_node,
     depart_solution_node,
     is_extension_node,
     exercise_title,
-    # visit_exercise_title,
-    # depart_exercise_title,
     exercise_subtitle,
-    # visit_exercise_subtitle,
-    # depart_exercise_subtitle,
     solution_title,
-    # visit_solution_title,
-    # depart_solution_title,
     solution_subtitle,
-    # visit_solution_subtitle,
-    # depart_solution_subtitle,
     exercise_latex_number_reference,
     visit_exercise_latex_number_reference,
     depart_exercise_latex_number_reference,

sphinx_exercise/nodes.py

@@ -4,9 +4,10 @@
 
 Sphinx Exercise Nodes
 
-:copyright: Copyright 2020 by the QuantEcon team, see AUTHORS
+:copyright: Copyright 2020-2021 by the Executable Books team, see AUTHORS
 :licences: see LICENSE for details
 """
+
 from sphinx.util import logging
 from docutils.nodes import Node
 from docutils import nodes as docutil_nodes
@@ -111,7 +112,7 @@ def depart_exercise_node(self, node: Node) -> None:
 def visit_exercise_enumerable_node(self, node: Node) -> None:
     """
     LaTeX Reference Structure is exercise:{label} and resolved by
-    exercise_latex_number_reference
+    exercise_latex_number_reference nodes (see below)
     """
     if isinstance(self, LaTeXTranslator):
         label = (

sphinx_exercise/post_transforms.py

@@ -35,7 +35,7 @@ def build_reference_node(app, target_node):
 
 class UpdateReferencesToEnumerated(SphinxPostTransform):
     """
-    Check :ref: made to enumerated nodes and update to :numref:
+    Check :ref: made to enumerated target nodes and update to :numref:
     """
 
     default_priority = 5
@@ -71,6 +71,9 @@ def run(self):
 class ResolveTitlesInExercises(SphinxPostTransform):
     """
     Resolve Titles for Exercise Nodes and Enumerated Exercise Nodes
+    for:
+        1. Numbering
+        2. Formatting Title and Subtitles into docutils.title node
     """
 
     default_priority = 20
@@ -117,10 +120,17 @@ def run(self):
 
 def resolve_solution_title(app, node, exercise_node):
     """
-    Resolve Solution Nodes
-    Note: Using a resolver function in case we need to resolve titles
+    Resolve Titles for Solution Nodes for:
+
+        1. Numbering of Target Exercise Nodes
+        2. Formatting Title and Subtitles into docutils.title node
+        3. Ensure mathjax is triggered for pages that include path
+           in titles inherited from Exercise Node
+
+    Note: Setup as a resolver function in case we need to resolve titles
     in references to solution nodes.
     """
+
     title = node.children[0]
     exercise_title = exercise_node.children[0]
     if isinstance(title, solution_title):
@@ -155,10 +165,6 @@ def resolve_solution_title(app, node, exercise_node):
 
 
 class ResolveTitlesInSolutions(SphinxPostTransform):
-    """
-    Resolve Titles for Solutions Nodes and merge in
-    the main title only from target_nodes
-    """
 
     default_priority = 21
 
@@ -209,19 +215,19 @@ def run(self):
                         for child in node.children:
                             new_node += child
                         node.replace_self(new_node)
-                    if isinstance(target_node, solution_node):
-                        pass
-                        # import pdb; pdb.set_trace()
                 if isinstance(target_node, solution_node):
+                    # TODO: Check if this condition is required?
+                    if not target_node.resolved_title:
+                        exercise_label = target_node.get("target_label")
+                        exercise_target = self.env.sphinx_exercise_registry[
+                            exercise_label
+                        ]  # noqa: E501
+                        exercise_node = exercise_target.get("node")
+                        target_node = resolve_solution_title(
+                            self.app, target_node, exercise_node
+                        )  # noqa: E501
                     title_text = target_node.children[0].astext()
                     inline = node.children[0]
                     inline.children = []
                     inline += docutil_nodes.Text(title_text)
                     node.children[0] = inline
-
-                    # TODO: Is it possible for the target_node not to be resolved?
-                    # if not target_node.resolved_title:
-                    #     exercise_label = target_node.get("target_label")
-                    #     exercise_target = self.env.sphinx_exercise_registry[exercise_label] # noqa: E501
-                    #     exercise_node = exercise_target.get("node")
-                    #     target_node = resolve_solution_title(self.app, target_node, exercise_node) # noqa: E501

sphinx_exercise/utils.py

@@ -18,11 +18,6 @@ def find_parent(env, node, parent_tag):
         ):
             return node.attributes["docname"]
 
-    if node.tagname == parent_tag:
-        return node.attributes["docname"]
-
-    return None
-
 
 def get_node_number(self, node, typ) -> str:
     """Get the number for the directive node for HTML."""