Address some doc bugs

mathics_django/doc/__init__.py

@@ -8,6 +8,6 @@
 import_and_load_builtins()
 
 # FIXME: should we really do this here?
-from mathics_django.doc.django_doc import MathicsDjangoDocumentation
+from mathics_django.doc.django_doc import DjangoDocumentation
 
-documentation = MathicsDjangoDocumentation()
+documentation = DjangoDocumentation()

mathics_django/doc/django_doc.py

@@ -11,13 +11,14 @@
 from mathics import settings
 from mathics.doc.common_doc import (
     DocChapter,
-    DocGuideSection,
+    DocPart,
+    DocSection,
+    DocSubsection,
     DocTest,
     DocTests,
     DocText,
     Documentation,
-    Tests,
-    XMLDoc,
+    DocumentationEntry,
     gather_tests,
     get_results_by_test,
     sorted_chapters,
@@ -28,21 +29,25 @@
 from mathics_django.settings import get_doctest_html_data_path
 
 # FIXME: remove globalness
+doctest_html_data_path = get_doctest_html_data_path(should_be_readable=True)
 try:
-    doctest_html_data_path = get_doctest_html_data_path(should_be_readable=True)
     with open(doctest_html_data_path, "rb") as doctest_html_data_file:
         doc_data = pickle.load(doctest_html_data_file)
 except IOError:
     print(f"Trouble reading Doc file {doctest_html_data_path}")
     doc_data = {}
 
 
-class DjangoDocElement(object):
+class DjangoDocElement:
+    """
+    Adds some HTML functions onto existing Django Document Elements.
+    """
+
     def href(self, ajax=False):
         if ajax:
-            return "javascript:loadDoc('%s')" % self.get_uri()
+            return f"javascript:loadDoc('{self.get_uri()}')"
         else:
-            return "/doc%s" % self.get_uri()
+            return f"/doc{self.get_uri()}"
 
     def get_prev(self):
         return self.get_prev_next()[0]
@@ -65,58 +70,27 @@ def get_title_html(self):
 
 
 class DjangoDocumentation(Documentation, DjangoDocElement):
+    def __init__(self):
+        super(DjangoDocumentation, self).__init__()
+        self.doc_class = DjangoDoc
+        self.doc_dir = settings.DOC_DIR
+        self.chapter_class = DjangoDocChapter
+        self.guide_section_class = DjangoDocGuideSection
+        self.part_class = DjangoDocPart
+        self.section_class = DjangoDocSection
+        self.subsection_class = DjangoDocSubsection
+
+        self.load_documentation_sources()
+        self.doctest_latex_pcl_path = settings.DOCTEST_LATEX_DATA_PCL
+        self.pymathics_doc_loaded = False
+        self.doc_data_file = settings.get_doctest_latex_data_path(
+            should_be_readable=True
+        )
+        self.title = "Overview"
+
     def __str__(self):
         return "\n\n\n".join(str(part) for part in self.parts)
 
-    def get_tests(self):
-        for part in self.parts:
-            for chapter in sorted_chapters(part.chapters):
-                tests = chapter.doc.get_tests()
-                if tests:
-                    yield Tests(part.title, chapter.title, "", tests)
-                for section in chapter.sections:
-                    if section.installed:
-                        if isinstance(section, DocGuideSection):
-                            for docsection in section.subsections:
-                                for docsubsection in docsection.subsections:
-                                    # FIXME: Something is weird here
-                                    # where tests for subsection items
-                                    # appear not as a collection but
-                                    # individually and need to be
-                                    # iterated below. Probably some
-                                    # other code is faulty and when
-                                    # fixed the below loop and
-                                    # collection into doctest_list[]
-                                    # will be removed.
-                                    doctest_list = []
-                                    index = 1
-                                    for doctests in docsubsection.items:
-                                        doctest_list += list(doctests.get_tests())
-                                        for test in doctest_list:
-                                            test.index = index
-                                            index += 1
-
-                                    if doctest_list:
-                                        yield Tests(
-                                            section.chapter.part.title,
-                                            section.chapter.title,
-                                            docsubsection.title,
-                                            doctest_list,
-                                        )
-                        else:
-                            tests = section.doc.get_tests()
-                            if tests:
-                                yield Tests(
-                                    part.title, chapter.title, section.title, tests
-                                )
-                                pass
-                            pass
-                        pass
-                    pass
-                pass
-            pass
-        return
-
     def get_uri(self) -> str:
         return "/"
 
@@ -174,33 +148,17 @@ def search_sections(section, result):
         return sorted_results
 
 
-class MathicsDjangoDocumentation(DjangoDocumentation):
-    def __init__(self, want_sorting=True):
-
-        self.doc_chapter_fn = DjangoDocChapter
-        self.doc_dir = settings.DOC_DIR
-        self.doc_fn = DjangoDoc
-        self.doc_guide_section_fn = DjangoDocGuideSection
-        self.doc_part_fn = DjangoDocPart
-        self.doc_section_fn = DjangoDocSection
-        self.doc_subsection_fn = DjangoDocSubsection
-        self.parts = []
-        self.parts_by_slug = {}
-        self.title = "Overview"
-
-        self.gather_doctest_data()
-
-
-class DjangoDoc(XMLDoc):
-    def __init__(self, doc, title, section):
+class DjangoDoc(DocumentationEntry):
+    def __init__(self, doc, title, section, key_prefix=None):
         self.title = title
-        if section:
-            chapter = section.chapter
-            part = chapter.part
-            # Note: we elide section.title
-            key_prefix = (part.title, chapter.title, title)
-        else:
-            key_prefix = None
+        if key_prefix is None:
+            if section is not None:
+                chapter = section.chapter
+                part = chapter.part
+                # Note: we elide section.title
+                key_prefix = (part.title, chapter.title, title)
+            else:
+                key_prefix = None
 
         self.rawdoc = doc
         self.items = gather_tests(
@@ -218,7 +176,6 @@ def get_tests(self):
         return tests
 
     def html(self):
-        counters = {}
         items = [item for item in self.items if not item.is_private()]
         title_line = self.title + "\n"
         if len(items) and items[0].text.startswith(title_line):
@@ -227,7 +184,7 @@ def html(self):
             # Or that is the intent. This code is a bit hacky.
             items[0].text = items[0].text[len(title_line) :]
 
-        text = "\n".join(item.html(counters) for item in items if not item.is_private())
+        text = "\n".join(item.html() for item in items if not item.is_private())
         if text == "":
             # HACK ALERT if text is "" we may have missed some test markup.
             return mark_safe(escape_html(self.rawdoc))
@@ -247,28 +204,24 @@ def get_uri(self) -> str:
         return f"/{self.part.slug}/{self.slug}/"
 
 
-class DjangoDocPart(DjangoDocElement):
-    def __init__(self, doc, title, is_reference=False):
-        self.doc = doc
-        self.title = title
-        self.slug = slugify(title)
-        self.chapters = []
-        self.chapters_by_slug = {}
-        self.is_reference = is_reference
-        self.is_appendix = False
-        doc.parts_by_slug[self.slug] = self
+class DjangoDocPart(DocPart, DjangoDocElement):
+    """
+    Represents one of the main parts of the document customized for Django. Parts
+    can be loaded from a mdoc file, generated automatically from
+    the docstrings of Builtin objects under `mathics.builtin`, or loaded
+    as a Mathics3 module.
+    """
 
-    def __str__(self):
-        return "%s\n\n%s" % (
-            self.title,
-            "\n".join(str(chapter) for chapter in sorted_chapters(self.chapters)),
-        )
+    chapter_class = DjangoDocChapter
+
+    def __init__(self, doc, title, is_reference=False):
+        super(DjangoDocPart, self).__init__(doc, title, is_reference)
 
     def get_collection(self):
         """Return a list of parts in this doc"""
         return self.doc.parts
 
-    def html(self, counters=None):
+    def html(self):
         if len(self.tests) == 0:
             return "\n"
         return '<ul class="tests">%s</ul>' % (
@@ -281,7 +234,7 @@ def get_uri(self) -> str:
         return f"/{self.slug}/"
 
 
-class DjangoDocSection(DjangoDocElement):
+class DjangoDocSection(DocSection, DjangoDocElement):
     """An object for a Django Documented Section.
     A Section is part of a Chapter. It can contain subsections.
     """
@@ -308,8 +261,7 @@ def __init__(
 
         if text.count("<dl>") != text.count("</dl>"):
             raise ValueError(
-                "Missing opening or closing <dl> tag in "
-                "{} documentation".format(title)
+                f"Missing opening or closing <dl> tag in {title} documentation"
             )
 
         # Needs to come after self.chapter is initialized since
@@ -342,7 +294,7 @@ def get_uri(self) -> str:
         return f"/{self.chapter.part.slug}/{self.chapter.slug}/{self.slug}/"
 
 
-class DjangoDocGuideSection(DjangoDocSection):
+class DjangoDocGuideSection(DjangoDocSection, DjangoDocElement):
     """An object for a Django Documented Guide Section.
     A Guide Section is part of a Chapter. "Colors" or "Special Functions"
     are examples of Guide Sections, and each contains a number of Sections.
@@ -370,8 +322,7 @@ def __init__(
 
         if text.count("<dl>") != text.count("</dl>"):
             raise ValueError(
-                "Missing opening or closing <dl> tag in "
-                "{} documentation".format(title)
+                f"Missing opening or closing <dl> tag in {title} documentation"
             )
         # print("YYY Adding section", title)
         chapter.sections_by_slug[self.slug] = self
@@ -381,7 +332,7 @@ def get_uri(self) -> str:
         return f"/{self.chapter.part.slug}/{self.chapter.slug}/guide/"
 
 
-class DjangoDocSubsection(DjangoDocElement):
+class DjangoDocSubsection(DocSubsection, DjangoDocElement):
     """An object for a Django Documented Subsection.
     A Subsection is part of a Section.
     """
@@ -451,8 +402,7 @@ def __init__(
 
         if text.count("<dl>") != text.count("</dl>"):
             raise ValueError(
-                "Missing opening or closing <dl> tag in "
-                "{} documentation".format(title)
+                f"Missing opening or closing <dl> tag in {title} documentation"
             )
         self.section.subsections_by_slug[self.slug] = self
 
@@ -521,7 +471,7 @@ def html(self) -> str:
 
 
 class DjangoDocTests(DocTests):
-    def html(self, counters=None):
+    def html(self):
         if len(self.tests) == 0:
             return "\n"
         return '<ul class="tests">%s</ul>' % (
@@ -532,6 +482,6 @@ def html(self, counters=None):
 
 
 class DjangoDocText(DocText):
-    def html(self, counters=None) -> str:
-        result = escape_html(self.text, counters=counters)
+    def html(self) -> str:
+        result = escape_html(self.text)
         return result