Guides from submodules

mathics/builtin/assignments/upvalues.py

@@ -2,7 +2,7 @@
 """
 UpValue-related assignments
 
-An <i>UpValue<i> is a definition associated with a symbols that does not appear directly its head.
+An <i>UpValue</i> is a definition associated with a symbols that does not appear directly its head.
 
 See <url>
 :Associating Definitions with Different Symbols:

mathics/doc/doc_entries.py

@@ -54,7 +54,7 @@
 )
 DL_RE = re.compile(r"(?s)<dl>(.*?)</dl>")
 HYPERTEXT_RE = re.compile(
-    r"(?s)<(?P<tag>em|url)>(\s*:(?P<text>.*?):\s*)?(?P<content>.*?)</(?P=tag)>"
+    r"(?s)<(?P<tag>em|url|pageref)>(\s*:(?P<text>.*?):\s*)?(?P<content>.*?)</(?P=tag)>"
 )
 IMG_PNG_RE = re.compile(
     r'<imgpng src="(?P<src>.*?)" title="(?P<title>.*?)" label="(?P<label>.*?)">'

mathics/doc/gather.py

@@ -16,7 +16,7 @@
 from mathics.core.builtin import Builtin, check_requires_list
 from mathics.core.util import IS_PYPY
 from mathics.doc.doc_entries import DocumentationEntry
-from mathics.doc.structure import DocChapter, DocGuideSection, DocSection, DocSubsection
+from mathics.doc.structure import DocChapter, DocGuideSection, DocSection
 
 
 def check_installed(src: Union[ModuleType, Builtin]) -> bool:
@@ -97,9 +97,10 @@ def doc_chapter(module, part, builtins_by_module):
     chapter = chapter_class(part, title, doc_class(text, title, None))
     part.chapters.append(chapter)
 
+    symbol_sections = gather_sections(chapter, module, builtins_by_module)
     assert len(chapter.sections) == 0
-
-    #    visited = set(sec.title for sec in symbol_sections)
+    chapter.sections.extend(symbol_sections)
+    visited = set(sec.title for sec in symbol_sections)
     # If the module is a package, add the guides and symbols from the submodules
     if module.__file__.endswith("__init__.py"):
         guide_sections, symbol_sections = gather_guides_and_sections(
@@ -113,23 +114,18 @@ def doc_chapter(module, part, builtins_by_module):
             else:
                 visited.add(sec.title)
                 chapter.sections.append(sec)
-    else:
-        symbol_sections = gather_sections(chapter, module, builtins_by_module)
-        chapter.sections.extend(symbol_sections)
-
     return chapter
 
 
-def gather_sections(chapter, module, builtins_by_module, section_class=None) -> list:
+def gather_sections(chapter, module, builtins_by_module) -> list:
     """Build a list of DocSections from a "top-level" module"""
     symbol_sections = []
     if skip_module_doc(module):
         return []
 
     part = chapter.part if chapter else None
     documentation = part.documentation if part else None
-    if section_class is None:
-        section_class = documentation.section_class if documentation else DocSection
+    section_class = documentation.section_class if documentation else DocSection
 
     # TODO: Check the reason why for the module
     # `mathics.builtin.numbers.constants`
@@ -168,29 +164,6 @@ def gather_sections(chapter, module, builtins_by_module, section_class=None) ->
     return symbol_sections
 
 
-def gather_subsections(chapter, section, module, builtins_by_module) -> list:
-    """Build a list of DocSubsections from a "top-level" module"""
-
-    part = chapter.part if chapter else None
-    documentation = part.documentation if part else None
-    section_class = documentation.subsection_class if documentation else DocSubsection
-
-    def section_function(
-        chapter,
-        title,
-        text,
-        operator=None,
-        installed=True,
-        in_guide=False,
-        summary_text="",
-    ):
-        return section_class(
-            chapter, section, title, text, operator, installed, in_guide, summary_text
-        )
-
-    return gather_sections(chapter, module, builtins_by_module, section_function)
-
-
 def gather_guides_and_sections(chapter, module, builtins_by_module):
     """
     Look at the submodules in module, and produce the guide sections
@@ -218,22 +191,33 @@ def gather_guides_and_sections(chapter, module, builtins_by_module):
         if skip_module_doc(sub_module):
             continue
 
+        submodule_symbol_sections = gather_sections(
+            chapter, sub_module, builtins_by_module
+        )
+        symbol_sections.extend(submodule_symbol_sections)
+
         title, text = get_module_doc(sub_module)
         installed = check_installed(sub_module)
 
+        if submodule_symbol_sections:
+            text = text + "\n\n<ul>\n"
+            for sym_sec in submodule_symbol_sections:
+                # TODO: improve the format
+                summary_text = sym_sec.summary_text
+                text = text + (
+                    f"<li><url>:'{sym_sec.title}':{docpath}{sym_sec.slug}</url>"
+                    f": {summary_text}"
+                    "</li>\n"
+                )
+            text = text + "\n\n</ul>"
+
         guide_section = guide_class(
             chapter=chapter,
             title=title,
             text=text,
             submodule=sub_module,
             installed=installed,
         )
-
-        submodule_symbol_sections = gather_subsections(
-            chapter, guide_section, sub_module, builtins_by_module
-        )
-
-        guide_section.subsections.extend(submodule_symbol_sections)
         guide_sections.append(guide_section)
 
         # TODO, handle recursively the submodules.
@@ -244,7 +228,7 @@ def gather_guides_and_sections(chapter, module, builtins_by_module):
         #                                       sub_module, builtins_by_module)
         #      symbol_sections.extend(deeper_symbol_sections)
         #      guide_sections.extend(deeper_guide_sections)
-    return guide_sections, []
+    return guide_sections, symbol_sections
 
 
 def get_module_doc(module: ModuleType) -> Tuple[str, str]:

mathics/doc/latex_doc.py

@@ -67,6 +67,7 @@
 )
 
 LATEX_TESTOUT_DELIM_RE = re.compile(r", ")
+URL_PAGEREF_RE = re.compile(r"<url>[:](?P<label>.*?)[:]/doc/(?P<ref>.*?)</url>")
 
 # The goal of the following pattern is to enclose the numbers included in
 # expressions produced by tests between ```\allowbreak{}```. The pattern matches
@@ -246,7 +247,13 @@ def repl_hypertext(match) -> str:
         content = content.replace(" ", "").replace("\n", "")
         if tag == "em":
             return r"\emph{%s}" % content
-        elif tag == "url":
+        elif tag == "pageref":
+            text = match.group("text")
+            if content.find("/doc/") == 0:
+                slug = "/".join(content.split("/")[2:]).rstrip("/")
+                return "%s (page \\pageref{%s})" % (text, latex_label_safe(slug))
+            tag = "url"
+        if tag == "url":
             text = match.group("text")
             if text is None:
                 return "\\url{%s}" % content
@@ -257,8 +264,6 @@ def repl_hypertext(match) -> str:
                 if content.find("/doc/") == 0:
                     slug = "/".join(content.split("/")[2:]).rstrip("/")
                     return "%s \\ref{%s}" % (text, latex_label_safe(slug))
-                    slug = "/".join(content.split("/")[2:]).rstrip("/")
-                    return "%s of section~\\ref{%s}" % (text, latex_label_safe(slug))
                 else:
                     return "\\href{%s}{%s}" % (content, text)
                 return "\\href{%s}{%s}" % (content, text)
@@ -737,11 +742,11 @@ def latex(self, doc_data: dict, quiet=False) -> str:
         sections = "\n\n".join(section.latex(doc_data) for section in self.subsections)
         slug = f"{self.chapter.part.slug}/{self.chapter.slug}/{self.slug}"
         section_string = (
-            "\n\n\\section{%s}{%s}\n" % (title, index)
+            "\n\n\\section*{%s}{%s}\n" % (title, index)
             + "\n\\label{%s}" % latex_label_safe(slug)
             + "\n\\sectionstart\n\n"
             + f"{content}"
-            # + ("\\addcontentsline{toc}{section}{%s}" % title)
+            + ("\\addcontentsline{toc}{section}{%s}" % title)
             + sections
             + "\\sectionend"
         )
@@ -763,6 +768,13 @@ def __init__(
         submodule,
         installed: bool = True,
     ):
+        def repl_pageref(match):
+            label = match.group(1)
+            ref = match.group(2)
+            slug = latex_label_safe("/".join(ref.split("/")[1:]).rstrip("/"))
+            return f"<pageref>:{label}:/doc/{ref}</pageref>"
+
+        text = URL_PAGEREF_RE.sub(repl_pageref, text)
         super().__init__(chapter, title, text, submodule, installed)
 
     def get_tests(self):

test/doc/test_latex.py

@@ -90,7 +90,7 @@ def test_load_latex_documentation():
     ).strip() == "Let's sketch the function\n\\begin{tests}"
     assert (
         first_section.latex(doc_data)[:30]
-    ).strip() == "\\section{Curve Sketching}{}"
+    ).strip() == "\\section*{Curve Sketching}{}"
     assert (
         third_chapter.latex(doc_data)[:38]
     ).strip() == "\\chapter{Further Tutorial Examples}"
@@ -102,11 +102,11 @@ def test_chapter():
     chapter = part.chapters_by_slug["testing-expressions"]
     print(chapter.sections_by_slug.keys())
     section = chapter.sections_by_slug["numerical-properties"]
-    latex_section_head = section.latex({})[:90].strip()
+    latex_section_head = section.latex({})[:73].strip()
     assert latex_section_head == (
         "\\section{Numerical Properties}\n"
-        "\\sectionstart\n\n\n\n"
-        "\\subsection*{CoprimeQ}\index{CoprimeQ}"
+        "\\sectionstart\n\n"
+        "\\begin{guidesectionintro}"
     )
     print(60 * "@")
     latex_chapter = chapter.latex({}, quiet=False)