guides as sections with indices

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]:

test/doc/test_latex.py

@@ -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)