Skip to content

Commit

Permalink
Preserve summary text to non-guide Django sections
Browse files Browse the repository at this point in the history
Also start regularizing section summary text here.
  • Loading branch information
rocky committed Jul 11, 2023
1 parent 28b8f0b commit f18ebbd
Show file tree
Hide file tree
Showing 4 changed files with 50 additions and 35 deletions.
46 changes: 26 additions & 20 deletions mathics/builtin/graphics.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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]
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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):
Expand Down Expand Up @@ -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):
Expand All @@ -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}}]]
Expand All @@ -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):
Expand All @@ -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:
Expand All @@ -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,
Expand Down Expand Up @@ -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):
Expand Down Expand Up @@ -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)
Expand Down
2 changes: 1 addition & 1 deletion mathics/builtin/layout.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 = {
Expand Down
28 changes: 16 additions & 12 deletions mathics/builtin/optiondoc.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
#
Expand All @@ -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):
"""
Expand Down Expand Up @@ -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):
Expand All @@ -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):
Expand Down Expand Up @@ -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):
Expand Down Expand Up @@ -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"
)

Expand Down Expand Up @@ -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>
Expand All @@ -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):
Expand Down
9 changes: 7 additions & 2 deletions mathics/doc/common_doc.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -367,6 +367,7 @@ def add_section(
operator,
is_guide: bool = False,
in_guide: bool = False,
summary_text="",
):
"""
Adds a DocSection or DocGuideSection
Expand Down Expand Up @@ -397,6 +398,7 @@ def add_section(
operator=operator,
installed=installed,
in_guide=in_guide,
summary_text=summary_text,
)
chapter.sections.append(section)

Expand Down Expand Up @@ -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)

Expand Down Expand Up @@ -779,7 +785,6 @@ def __init__(
in_guide=False,
summary_text="",
):

self.chapter = chapter
self.in_guide = in_guide
self.installed = installed
Expand Down

0 comments on commit f18ebbd

Please sign in to comment.