Preserve summary text to non-guide Django sections

Also start regularizing section summary text here.

mathics/builtin/graphics.py

@@ -5,9 +5,6 @@
 Drawing Graphics
 """
 
-# This following line tells documentation how to sort this module
-sort_order = "mathics.builtin.drawing-graphics"
-
 from math import sqrt
 
 from mathics.builtin.base import Builtin
@@ -52,6 +49,9 @@
 )
 from mathics.eval.nevaluator import eval_N
 
+# This following line tells documentation how to sort this module
+sort_order = "mathics.builtin.drawing-graphics"
+
 GRAPHICS_OPTIONS = {
     "AspectRatio": "Automatic",
     "Axes": "False",
@@ -431,7 +431,7 @@ class AbsoluteThickness(_Thickness):
      = -Graphics-
     """
 
-    summary_text = "graphics directive be specifying absolute line thickness"
+    summary_text = "graphics directive for the absolute line thickness"
 
     def get_thickness(self):
         return self.graphics.translate_absolute((self.value, 0))[0]
@@ -485,7 +485,7 @@ class PointSize(_Size):
     = {-Graphics3D-, -Graphics3D-, -Graphics3D-}
     """
 
-    summary_text = "graphics directive specifying relative sizes of points"
+    summary_text = "graphics directive for relative sizes of points"
 
     def get_absolute_size(self):
         if self.graphics.view_width is None:
@@ -592,15 +592,16 @@ class Polygon(Builtin):
 
     Notice that there is a line connecting from the last point to the first one.
 
-    A point is an element of the polygon if a ray from the point in any direction in the plane crosses the boundary line segments an odd number of times.
+    A point is an element of the polygon if a ray from the point in any direction in \
+    the plane crosses the boundary line segments an odd number of times.
     >> Graphics[Polygon[{{150,0},{121,90},{198,35},{102,35},{179,90}}]]
     = -Graphics-
 
     >> Graphics3D[Polygon[{{0,0,0},{0,1,1},{1,0,0}}]]
     = -Graphics3D-
     """
 
-    summary_text = "a polygon in 2D or 3D"
+    summary_text = "graphics primitive for a polygon in 2D or 3D"
 
 
 class RegularPolygon(Builtin):
@@ -628,7 +629,7 @@ class RegularPolygon(Builtin):
     = -Graphics-
     """
 
-    summary_text = "a regular polygon in 2D"
+    summary_text = "graphics primitve for a regular polygon in 2D"
 
 
 class Arrow(Builtin):
@@ -645,10 +646,12 @@ class Arrow(Builtin):
       <dd>represents a line with arrow that keeps a distance of $s$ from $p1$ and $p2$.
 
       <dt>'Arrow[{$point_1$, $point_2$}, {$s1$, $s2$}]'
-      <dd>represents a line with arrow that keeps a distance of $s1$ from $p1$ and a distance of $s2$ from $p2$.
+      <dd>represents a line with arrow that keeps a distance of $s1$ from $p1$ and a \
+          distance of $s2$ from $p2$.
 
       <dt>'Arrow[{$point_1$, $point_2$}, {$s1$, $s2$}]'
-      <dd>represents a line with arrow that keeps a distance of $s1$ from $p1$ and a distance of $s2$ from $p2$.
+      <dd>represents a line with arrow that keeps a distance of $s1$ from $p1$ and a \
+          distance of $s2$ from $p2$.
     </dl>
 
     >> Graphics[Arrow[{{0,0}, {1,1}}]]
@@ -668,7 +671,7 @@ class Arrow(Builtin):
      = {-Graphics-, -Graphics-, -Graphics-, -Graphics-, -Graphics-}
     """
 
-    summary_text = "graphics primitive to specify arbitrary graphical arrows"
+    summary_text = "graphics primitive for arbitrary graphical arrows"
 
 
 class Arrowheads(_GraphicsDirective):
@@ -680,19 +683,24 @@ class Arrowheads(_GraphicsDirective):
 
     <dl>
       <dt>'Arrowheads[$s$]'
-      <dd>specifies that Arrow[] draws one arrow of size $s$ (relative to width of image, defaults to 0.04).
+      <dd>specifies that Arrow[] draws one arrow of size $s$ (relative to width of \
+          image, defaults to 0.04).
 
       <dt>'Arrowheads[{$spec1$, $spec2$, ..., $specn$}]'
-      <dd>specifies that Arrow[] draws n arrows as defined by $spec1$, $spec2$, ... $specn$.
+      <dd>specifies that Arrow[] draws n arrows as defined by $spec1$, $spec2$, \
+          ... $specn$.
 
       <dt>'Arrowheads[{{$s$}}]'
       <dd>specifies that one arrow of size $s$ should be drawn.
 
       <dt>'Arrowheads[{{$s$, $pos$}}]'
-      <dd>specifies that one arrow of size $s$ should be drawn at position $pos$ (for the arrow to be on the line, $pos$ has to be between 0, i.e. the start for the line, and 1, i.e. the end of the line).
+      <dd>specifies that one arrow of size $s$ should be drawn at position $pos$ (for \
+          the arrow to be on the line, $pos$ has to be between 0, i.e. the start for \
+          the line, and 1, i.e. the end of the line).
 
       <dt>'Arrowheads[{{$s$, $pos$, $g$}}]'
-      <dd>specifies that one arrow of size $s$ should be drawn at position $pos$ using Graphics $g$.
+      <dd>specifies that one arrow of size $s$ should be drawn at position $pos$ \
+          using Graphics $g$.
     </dl>
 
     Arrows on both ends can be achieved using negative sizes:
@@ -711,9 +719,7 @@ class Arrowheads(_GraphicsDirective):
 
     default_size = 0.04
 
-    summary_text = (
-        "graphics directive specifying the form and placement of an arrowhead"
-    )
+    summary_text = "graphics directive for the form and placement of an arrowhead"
 
     symbolic_sizes = {
         "System`Tiny": 3,
@@ -1232,7 +1238,7 @@ class Circle(Builtin):
     """
 
     rules = {"Circle[]": "Circle[{0, 0}]"}
-    summary_text = "empty circle, ellipse, or arc graphics primitive"
+    summary_text = "graphics primitive for an empty circle, ellipse, or arc"
 
 
 class Disk(Builtin):
@@ -1493,7 +1499,7 @@ class Thickness(_Thickness):
      = -Graphics-
     """
 
-    summary_text = "graphics directive to specify line thicknesses"
+    summary_text = "graphics directive for line thicknesses"
 
     def get_thickness(self):
         return self.graphics.translate_relative(self.value)

mathics/builtin/layout.py

@@ -420,7 +420,7 @@ class Style(Builtin):
     </dl>
     """
 
-    summary_text = "wrapper specifying styles and style options to apply"
+    summary_text = "wrapper for styles and style options to apply"
     options = {"ImageSizeMultipliers": "Automatic"}
 
     rules = {

mathics/builtin/optiondoc.py

@@ -3,13 +3,11 @@
 """
 Drawing Options and Option Values
 
-The various common Plot and Graphics options, along with the meaning of specific option values are described here.
+The various common Plot and Graphics options, along with the meaning of specific \
+option values are described here.
 
 """
 
-# This tells documentation how to sort this module
-sort_order = "mathics.builtin.drawing-options-and-option-values"
-
 # Until we have a better documentation system in place, we define classes for
 # options. They are Builtins, even though they largely aren't.
 #
@@ -19,6 +17,9 @@
 
 from mathics.builtin.base import Builtin
 
+# This tells documentation how to sort this module
+sort_order = "mathics.builtin.drawing-options-and-option-values"
+
 
 class Automatic(Builtin):
     """
@@ -99,14 +100,15 @@ class ChartLabels(Builtin):
 
     <dl>
       <dt>'ChartLabels'
-      <dd>is a charting option that specifies what labels should be used for chart elements.
+      <dd>is a charting option that specifies what labels should be used for chart \
+          elements.
     </dl>
 
     >> PieChart[{30, 20, 10}, ChartLabels -> {Dogs, Cats, Fish}]
      = -Graphics-
     """
 
-    summary_text = "charting option specifying whether to label chart"
+    summary_text = "charting option for whether to label chart"
 
 
 class ChartLegends(Builtin):
@@ -115,11 +117,12 @@ class ChartLegends(Builtin):
 
     <dl>
       <dt>'ChartLegends'
-      <dd>is an option for charting functions that specifies the legends to be used for chart elements.
+      <dd>is an option for charting functions that specifies the legends to be used \
+          for chart elements.
     </dl>
     """
 
-    summary_text = "chart option giving legends to a chart"
+    summary_text = "chart option for giving legends to a chart"
 
 
 class Filling(Builtin):
@@ -173,7 +176,7 @@ class ImageSize(Builtin):
      = -Graphics-
     """
 
-    summary_text = "image option specifying the size of the final picture"
+    summary_text = "image option for the size of the final picture"
 
 
 class Joined(Builtin):
@@ -211,7 +214,7 @@ class MaxRecursion(Builtin):
     """
 
     summary_text = (
-        "function option specifying the maximum number of recursive "
+        "function option for the maximum number of recursive "
         "subdivisions the function can perform"
     )
 
@@ -298,7 +301,8 @@ class TicksStyle(Builtin):
 
     <dl>
       <dt>'TicksStyle'
-      <dd>is an option for graphics functions which specifies how ticks should be rendered.
+      <dd>is an option for graphics functions which specifies how ticks should be \
+          rendered.
     </dl>
 
     <ul>
@@ -311,7 +315,7 @@ class TicksStyle(Builtin):
      = -Graphics-
     """
 
-    summary_text = "graph option specifying the format of tick marks on axes"
+    summary_text = "graph option for the format of tick marks on axes"
 
 
 class Top(Builtin):

mathics/doc/common_doc.py

@@ -123,7 +123,7 @@
 
 
 def _replace_all(text, pairs):
-    for (i, j) in pairs:
+    for i, j in pairs:
         text = text.replace(i, j)
     return text
 
@@ -367,6 +367,7 @@ def add_section(
         operator,
         is_guide: bool = False,
         in_guide: bool = False,
+        summary_text="",
     ):
         """
         Adds a DocSection or DocGuideSection
@@ -397,6 +398,7 @@ def add_section(
                 operator=operator,
                 installed=installed,
                 in_guide=in_guide,
+                summary_text=summary_text,
             )
             chapter.sections.append(section)
 
@@ -556,13 +558,17 @@ def doc_sections(self, sections, modules_seen, chapter):
                 not hasattr(instance, "no_doc") or not instance.no_doc
             ):
                 name = instance.get_name(short=True)
+                summary_text = (
+                    instance.summary_text if hasattr(instance, "summary_text") else ""
+                )
                 self.add_section(
                     chapter,
                     name,
                     instance,
                     instance.get_operator(),
                     is_guide=False,
                     in_guide=False,
+                    summary_text=summary_text,
                 )
                 modules_seen.add(instance)
 
@@ -779,7 +785,6 @@ def __init__(
         in_guide=False,
         summary_text="",
     ):
-
         self.chapter = chapter
         self.in_guide = in_guide
         self.installed = installed