Merge pull request #58 from executablebooks/latex-features

ENH: Add latex and support for non-title nodes

Author: AakashGfude

docs/source/conf.py

@@ -18,6 +18,8 @@
     "sphinx_togglebutton",
 ]
 
+bibtex_bibfiles = ["references.bib"]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 

setup.py

@@ -27,6 +27,7 @@
         "pytest-regressions",
         "beautifulsoup4",
         "myst-parser",
+        "texsoup",
     ],
     "rtd": [
         "sphinx>=3.0",

sphinx_proof/__init__.py

@@ -76,18 +76,21 @@ def setup(app: Sphinx) -> Dict[str, Any]:
         proof_node,
         singlehtml=(visit_proof_node, depart_proof_node),
         html=(visit_proof_node, depart_proof_node),
+        latex=(visit_proof_node, depart_proof_node),
     )
     app.add_node(
         unenumerable_node,
         singlehtml=(visit_unenumerable_node, depart_unenumerable_node),
         html=(visit_unenumerable_node, depart_unenumerable_node),
+        latex=(visit_unenumerable_node, depart_unenumerable_node),
     )
     app.add_enumerable_node(
         enumerable_node,
         "proof",
         None,
         singlehtml=(visit_enumerable_node, depart_enumerable_node),
         html=(visit_enumerable_node, depart_enumerable_node),
+        latex=(visit_enumerable_node, depart_enumerable_node),
     )
 
     return {

sphinx_proof/domain.py

@@ -7,7 +7,7 @@
 :copyright: Copyright 2020 by the QuantEcon team, see AUTHORS
 :licences: see LICENSE for details
 """
-from typing import Any, Dict, Tuple, List
+from typing import Any, Dict, Tuple, List, Callable
 from docutils.nodes import Element, Node, document, system_message
 from sphinx.environment import BuildEnvironment
 from sphinx.addnodes import pending_xref
@@ -21,6 +21,7 @@
 from docutils import nodes
 from .directive import ProofDirective
 from .proof_type import PROOF_TYPES
+from copy import copy
 
 logger = logging.getLogger(__name__)
 
@@ -38,6 +39,7 @@ def generate(self, docnames=None) -> Tuple[Dict[str, Any], bool]:
             return content, True
 
         proofs = self.domain.env.proof_list
+        # {'theorem-0': {'docname': 'start/overview', 'type': 'theorem', 'ids': ['theorem-0'], 'label': 'theorem-0', 'prio': 0, 'nonumber': False}} # noqa: E501
 
         # name, subtype, docname, typ, anchor, extra, qualifier, description
         for anchor, values in proofs.items():
@@ -71,11 +73,23 @@ class ProofDomain(Domain):
     name = "prf"
     label = "Proof Domain"
 
-    roles = {"ref": ProofXRefRole()}
+    roles = {"ref": ProofXRefRole()}  # role name -> role callable
 
-    indices = {ProofIndex}
+    indices = {ProofIndex}  # a list of index subclasses
 
-    directives = {**{"proof": ProofDirective}, **PROOF_TYPES}
+    directives = {**{"proof": ProofDirective}, **PROOF_TYPES}  # list of directives
+
+    enumerable_nodes = {}  # type: Dict[[Node], Tuple[str, Callable]]
+
+    def __init__(self, env: "BuildEnvironment") -> None:
+        super().__init__(env)
+
+        # set up enumerable nodes
+        self.enumerable_nodes = copy(
+            self.enumerable_nodes
+        )  # create a copy for this instance
+        for node, settings in env.app.registry.enumerable_nodes.items():
+            self.enumerable_nodes[node] = settings
 
     def resolve_xref(
         self,
@@ -87,7 +101,14 @@ def resolve_xref(
         node: pending_xref,
         contnode: Element,
     ) -> Element:
-
+        """
+        Resolve the pending_xref node with the given typ and target. This method should
+        return a new node, to replace the xref node, containing the contnode which is
+        the markup content of the cross-reference. If no resolution can be found, None
+        can be returned; the xref node will then given to the missing-reference event,
+        and if that yields no resolution, replaced by contnode.The method can also raise
+        sphinx.environment.NoUri to suppress the missing-reference event being emitted.
+        """
         try:
             match = env.proof_list[target]
         except Exception:
@@ -98,7 +119,6 @@ def resolve_xref(
 
         todocname = match["docname"]
         title = contnode[0]
-
         if target in contnode[0]:
             number = ""
             if not env.proof_list[target]["nonumber"]:

sphinx_proof/nodes.py

@@ -7,9 +7,13 @@
 :copyright: Copyright 2020 by the QuantEcon team, see AUTHORS
 :licences: see LICENSE for details
 """
-from sphinx.builders.html import HTMLTranslator
 from docutils import nodes
 from docutils.nodes import Node
+from sphinx.writers.latex import LaTeXTranslator
+
+CR = "\n"
+latex_admonition_start = CR + "\\begin{sphinxadmonition}{note}"
+latex_admonition_end = "\\end{sphinxadmonition}" + CR
 
 
 class proof_node(nodes.Admonition, nodes.Element):
@@ -25,35 +29,53 @@ class unenumerable_node(nodes.Admonition, nodes.Element):
 
 
 def visit_enumerable_node(self, node: Node) -> None:
-    self.body.append(self.starttag(node, "div", CLASS="admonition"))
+    if isinstance(self, LaTeXTranslator):
+        docname = find_parent(self.builder.env, node, "section")
+        self.body.append("\\label{" + f"{docname}:{node.attributes['label']}" + "}")
+        self.body.append(latex_admonition_start)
+    else:
+        self.body.append(self.starttag(node, "div", CLASS="admonition"))
 
 
 def depart_enumerable_node(self, node: Node) -> None:
     typ = node.attributes.get("type", "")
-
-    # Find index in list of 'Proof #'
-    number = get_node_number(self, node)
-    idx = self.body.index(f"Proof {number} ")
-    self.body[idx] = f"{typ.title()} {number} "
-    self.body.append("</div>")
+    if isinstance(self, LaTeXTranslator):
+        number = get_node_number(self, node)
+        idx = list_rindex(self.body, latex_admonition_start) + 2
+        self.body.insert(idx, f"{typ.title()} {number}")
+        self.body.append(latex_admonition_end)
+    else:
+        # Find index in list of 'Proof #'
+        number = get_node_number(self, node)
+        idx = self.body.index(f"Proof {number} ")
+        self.body[idx] = f"{typ.title()} {number} "
+        self.body.append("</div>")
 
 
 def visit_unenumerable_node(self, node: Node) -> None:
-    self.body.append(self.starttag(node, "div", CLASS="admonition"))
+    if isinstance(self, LaTeXTranslator):
+        docname = find_parent(self.builder.env, node, "section")
+        self.body.append("\\label{" + f"{docname}:{node.attributes['label']}" + "}")
+        self.body.append(latex_admonition_start)
+    else:
+        self.body.append(self.starttag(node, "div", CLASS="admonition"))
 
 
 def depart_unenumerable_node(self, node: Node) -> None:
     typ = node.attributes.get("type", "")
     title = node.attributes.get("title", "")
-
-    if title == "":
-        idx = len(self.body) - self.body[-1::-1].index('<p class="admonition-title">')
+    if isinstance(self, LaTeXTranslator):
+        idx = list_rindex(self.body, latex_admonition_start) + 2
+        self.body.insert(idx, f"{typ.title()}")
+        self.body.append(latex_admonition_end)
     else:
-        idx = self.body.index(title)
-
-    element = f"<span>{typ.title()} </span>"
-    self.body.insert(idx, element)
-    self.body.append("</div>")
+        if title == "":
+            idx = list_rindex(self.body, '<p class="admonition-title">') + 1
+        else:
+            idx = list_rindex(self.body, title)
+        element = f"<span>{typ.title()} </span>"
+        self.body.insert(idx, element)
+        self.body.append("</div>")
 
 
 def visit_proof_node(self, node: Node) -> None:
@@ -64,8 +86,44 @@ def depart_proof_node(self, node: Node) -> None:
     pass
 
 
-def get_node_number(self: HTMLTranslator, node: Node) -> str:
+def get_node_number(self, node: Node) -> str:
+    """Get the number for the directive node for HTML."""
     key = "proof"
     ids = node.attributes.get("ids", [])[0]
-    number = self.builder.fignumbers.get(key, {}).get(ids, ())
+    if isinstance(self, LaTeXTranslator):
+        docname = find_parent(self.builder.env, node, "section")
+        fignumbers = self.builder.env.toc_fignumbers.get(
+            docname, {}
+        )  # Latex does not have builder.fignumbers
+    else:
+        fignumbers = self.builder.fignumbers
+    number = fignumbers.get(key, {}).get(ids, ())
     return ".".join(map(str, number))
+
+
+def find_parent(env, node, parent_tag):
+    """Find the nearest parent node with the given tagname."""
+    while True:
+        node = node.parent
+        if node is None:
+            return None
+        # parent should be a document in toc
+        if (
+            "docname" in node.attributes
+            and env.titles[node.attributes["docname"]].astext().lower()
+            in node.attributes["names"]
+        ):
+            return node.attributes["docname"]
+
+    if node.tagname == parent_tag:
+        return node.attributes["docname"]
+
+    return None
+
+
+def list_rindex(li, x) -> int:
+    """Getting the last occurence of an item in a list."""
+    for i in reversed(range(len(li))):
+        if li[i] == x:
+            return i
+    raise ValueError("{} is not in list".format(x))

tests/test_build.py

@@ -2,6 +2,14 @@
 import pytest
 
 
+@pytest.mark.sphinx("html", testroot="missingref")
+def test_missing_ref(app, warnings):
+    # Clean build
+    app.build()
+    assert "WARNING: label 'foo' not found" in warnings(app)
+
+
+# Tests for algorithms
 @pytest.mark.sphinx("html", testroot="mybook")
 @pytest.mark.parametrize(
     "idir", ["_algo_labeled_titled_with_classname.html", "_algo_nonumber.html"]
@@ -38,3 +46,28 @@ def test_reference(app, idir, file_regression):
 def test_duplicate_label(app, warnings):
     app.build()
     assert "WARNING: duplicate algorithm label" in warnings(app)
+
+
+# Tests for Proofs
+@pytest.mark.sphinx("html", testroot="mybook")
+@pytest.mark.parametrize(
+    "idir",
+    [
+        "_proof_with_classname.html",
+        "_proof_no_classname.html",
+        "_proof_with_argument_content.html",
+        "_proof_with_labeled_math.html",
+        "_proof_with_unlabeled_math.html",
+    ],
+)
+def test_proof(app, idir, file_regression):
+    """Test proof directive markup."""
+    app.build()
+    path_proof_directive = app.outdir / "proof" / idir
+    assert path_proof_directive.exists()
+
+    # get content markup
+    soup = BeautifulSoup(path_proof_directive.read_text(encoding="utf8"), "html.parser")
+
+    proof = soup.select("div.proof")[0]
+    file_regression.check(str(proof), basename=idir.split(".")[0], extension=".html")