From 81acf82f03bec414421bcea5f69badd84d63e424 Mon Sep 17 00:00:00 2001 From: rocky Date: Mon, 10 Jul 2023 09:16:18 -0400 Subject: [PATCH 1/7] What we need to get PDF doc to build... * Some references corrected. * Remove duplicate sections (in both test and doc) in guide sections * Fix a small markup typo in ComplexExpand formatting --- mathics/builtin/drawing/__init__.py | 12 +-- mathics/builtin/drawing/plot.py | 6 +- mathics/builtin/files_io/importexport.py | 97 ++++++++++++------------ mathics/builtin/forms/__init__.py | 3 +- mathics/builtin/numbers/hyperbolic.py | 2 +- mathics/builtin/options.py | 22 +++--- mathics/doc/common_doc.py | 12 ++- 7 files changed, 83 insertions(+), 71 deletions(-) diff --git a/mathics/builtin/drawing/__init__.py b/mathics/builtin/drawing/__init__.py index eec632ffb..ce5e3a26e 100644 --- a/mathics/builtin/drawing/__init__.py +++ b/mathics/builtin/drawing/__init__.py @@ -4,19 +4,21 @@ Showing something visually can be done in a number of ways: """ diff --git a/mathics/builtin/drawing/plot.py b/mathics/builtin/drawing/plot.py index 7c5421da4..80c79cbc6 100644 --- a/mathics/builtin/drawing/plot.py +++ b/mathics/builtin/drawing/plot.py @@ -1539,7 +1539,7 @@ class DiscretePlot(_Plot): = -Graphics- Compare with :'Plot': - /doc/reference-of-built-in-symbols/graphics-drawing-and-images/plotting-data/plot/. + /doc/reference-of-built-in-symbols/graphics-and-drawing/plotting-data/plot/. """ attributes = A_HOLD_ALL | A_PROTECTED @@ -1969,13 +1969,13 @@ class ListPlot(_ListPlot): = -Graphics- Compare with :'Plot': - /doc/reference-of-built-in-symbols/graphics-drawing-and-images/plotting-data/plot/. + /doc/reference-of-built-in-symbols/graphics-and-drawing/plotting-data/plot/. >> ListPlot[Table[n ^ 2, {n, 30}], Filling->Axis] = -Graphics- Compare with :'Plot': - /doc/reference-of-built-in-symbols/graphics-drawing-and-images/plotting-data/plot. + /doc/reference-of-built-in-symbols/graphics-and-drawing/plotting-data/plot. """ options = Graphics.options.copy() diff --git a/mathics/builtin/files_io/importexport.py b/mathics/builtin/files_io/importexport.py index ad8353e06..1aa656f1d 100644 --- a/mathics/builtin/files_io/importexport.py +++ b/mathics/builtin/files_io/importexport.py @@ -10,17 +10,13 @@ :Export: /doc/reference-of-built-in-symbols/importing-and-exporting/export, \ while -:$InputFormats: -/doc/reference-of-built-in-symbols/importing-and-exporting/$inputformats \ +:$ImportFormats: +/doc/reference-of-built-in-symbols/importing-and-exporting/$importformats \ does the corresponding thing for :Import: /doc/reference-of-built-in-symbols/importing-and-exporting/import. """ -# This tells documentation how to sort this module -# Here we are also hiding "file_io" since this can erroneously appear at the top level. -sort_order = "mathics.builtin.importing-and-exporting" - import base64 import mimetypes import os @@ -47,6 +43,10 @@ SymbolToString, ) +# This tells documentation how to sort this module +# Here we are also hiding "file_io" since this can erroneously appear at the top level. +sort_order = "mathics.builtin.importing-and-exporting" + mimetypes.add_type("application/vnd.wolfram.mathematica.package", ".m") SymbolClose = Symbol("Close") @@ -947,46 +947,6 @@ def _importer_exporter_options( return stream_options, custom_options -class ImportFormats(Predefined): - """ - :WMA link:https://reference.wolfram.com/language/ref/$ImportFormats.html - -
-
'$ImportFormats' -
returns a list of file formats supported by Import. -
- - >> $ImportFormats - = {...CSV,...JSON,...Text...} - """ - - name = "$ImportFormats" - summary_text = "list supported import formats" - - def evaluate(self, evaluation: Evaluation): - return to_mathics_list(*sorted(IMPORTERS.keys()), elements_conversion_fn=String) - - -class ExportFormats(Predefined): - """ - :WMA link:https://reference.wolfram.com/language/ref/$ExportFormats.html - -
-
'$ExportFormats' -
returns a list of file formats supported by Export. -
- - >> $ExportFormats - = {...CSV,...SVG,...Text...} - """ - - name = "$ExportFormats" - summary_text = "list supported export formats" - - def evaluate(self, evaluation: Evaluation): - return to_mathics_list(*sorted(EXPORTERS.keys()), elements_conversion_fn=String) - - class ConverterDumpsExtensionMappings(Predefined): """ ## :internal native symbol: @@ -1037,6 +997,46 @@ def evaluate(self, evaluation: Evaluation): return from_python(FORMATMAPPINGS) +class ExportFormats(Predefined): + """ + :WMA link:https://reference.wolfram.com/language/ref/$ExportFormats.html + +
+
'$ExportFormats' +
returns a list of file formats supported by Export. +
+ + >> $ExportFormats + = {...CSV,...SVG,...Text...} + """ + + name = "$ExportFormats" + summary_text = "list supported export formats" + + def evaluate(self, evaluation: Evaluation): + return to_mathics_list(*sorted(EXPORTERS.keys()), elements_conversion_fn=String) + + +class ImportFormats(Predefined): + """ + :WMA link:https://reference.wolfram.com/language/ref/$ImportFormats.html + +
+
'$ImportFormats' +
returns a list of file formats supported by Import. +
+ + >> $ImportFormats + = {...CSV,...JSON,...Text...} + """ + + name = "$ImportFormats" + summary_text = "list supported import formats" + + def evaluate(self, evaluation: Evaluation): + return to_mathics_list(*sorted(IMPORTERS.keys()), elements_conversion_fn=String) + + class RegisterImport(Builtin): """ ## :internal native symbol: @@ -1183,7 +1183,8 @@ class RegisterExport(Builtin):
'RegisterExport["$format$", $func$]' -
register '$func$' as the default function used when exporting from a file of type '"$format$"'. +
register '$func$' as the default function used when exporting from a file of \ + type '"$format$"'.
Simple text exporter @@ -1198,7 +1199,7 @@ class RegisterExport(Builtin): #> DeleteFile["sample.txt"] - Very basic encrypted text exporter + Very basic encrypted text exporter: >> ExampleExporter2[filename_, data_, opts___] := Module[{strm = OpenWrite[filename], char}, (* TODO: Check data *) char = FromCharacterCode[Mod[ToCharacterCode[data] - 84, 26] + 97]; WriteString[strm, char]; Close[strm]] >> ImportExport`RegisterExport["ExampleFormat2", ExampleExporter2] diff --git a/mathics/builtin/forms/__init__.py b/mathics/builtin/forms/__init__.py index a930b0314..08079cc3c 100644 --- a/mathics/builtin/forms/__init__.py +++ b/mathics/builtin/forms/__init__.py @@ -1,7 +1,8 @@ """ Forms of Input and Output -A Form format specifies the way Mathics Expression input is read or output written. +A Form format specifies the way Mathics Expression input is read or output \ +written. The variable :$OutputForms': /doc/reference-of-built-in-symbols/forms-of-input-and-output/form-variables/$outputforms/ \ diff --git a/mathics/builtin/numbers/hyperbolic.py b/mathics/builtin/numbers/hyperbolic.py index 774c0f386..44670b15c 100644 --- a/mathics/builtin/numbers/hyperbolic.py +++ b/mathics/builtin/numbers/hyperbolic.py @@ -262,7 +262,7 @@ class ComplexExpand(SympyFunction):
'ComplexExpand[$expr$]'
expands $expr$ assuming that all variables are real. -
'ComplexExpand[$expr$,{$x1$,$x2$, ...}] +
'ComplexExpand[$expr$,{$x1$,$x2$, ...}]'
expands $expr$ assuming that variables matching any of the $xi$ are complex. diff --git a/mathics/builtin/options.py b/mathics/builtin/options.py index 7e01f61f6..e3d314de8 100644 --- a/mathics/builtin/options.py +++ b/mathics/builtin/options.py @@ -169,21 +169,21 @@ def matched(): class None_(Predefined): """ - :WMA link:https://reference.wolfram.com/language/ref/None.html + :WMA link:https://reference.wolfram.com/language/ref/None.html -
-
'None' -
is a setting value for many options. -
+
+
'None' +
is a setting value for many options. +
- Plot3D shows the mesh grid between computed points by default. This the - :Mesh: - /doc/reference-of-built-in-symbols/drawing-option-and-values/mesh option. + Plot3D shows the mesh grid between computed points by default. This the + :Mesh: + /doc/reference-of-built-in-symbols/drawing-options-and-option-values/mesh option. - However, you hide the mesh by setting the 'Mesh' option value to 'None': + However, you hide the mesh by setting the 'Mesh' option value to 'None': - >> Plot3D[{x^2 + y^2, -x^2 - y^2}, {x, -2, 2}, {y, -2, 2}, BoxRatios-> Automatic, Mesh->None] - = -Graphics3D- + >> Plot3D[{x^2 + y^2, -x^2 - y^2}, {x, -2, 2}, {y, -2, 2}, BoxRatios-> Automatic, Mesh->None] + = -Graphics3D- """ name = "None" diff --git a/mathics/doc/common_doc.py b/mathics/doc/common_doc.py index 38a134f9a..e8fbf89ad 100644 --- a/mathics/doc/common_doc.py +++ b/mathics/doc/common_doc.py @@ -456,6 +456,7 @@ def doc_part(self, title, modules, builtins_by_module, start): builtin_part = self.doc_part_fn(self, title, is_reference=start) modules_seen = set([]) + submodule_names_seen = set([]) want_sorting = True if want_sorting: @@ -504,6 +505,8 @@ def doc_part(self, title, modules, builtins_by_module, start): continue submodule_name = get_doc_name_from_module(submodule) + if submodule_name in submodule_names_seen: + continue section = self.add_section( chapter, submodule_name, @@ -513,6 +516,7 @@ def doc_part(self, title, modules, builtins_by_module, start): in_guide=True, ) modules_seen.add(submodule) + submodule_names_seen.add(submodule_name) guide_section.subsections.append(section) builtins = builtins_by_module.get(submodule.__name__, []) @@ -521,13 +525,17 @@ def doc_part(self, title, modules, builtins_by_module, start): if hasattr(instance, "no_doc") and instance.no_doc: continue - modules_seen.add(instance) name = instance.get_name(short=True) + if name in submodule_names_seen: + continue + + submodule_names_seen.add(name) + modules_seen.add(instance) self.add_subsection( chapter, section, - instance.get_name(short=True), + name, instance, instance.get_operator(), in_guide=True, From 7e92624a0dd76f6d0652c89fd55c17fb96d437b1 Mon Sep 17 00:00:00 2001 From: rocky Date: Mon, 10 Jul 2023 16:09:16 -0400 Subject: [PATCH 2/7] Combine CProfiling and Tracing Both are pretty short and it makes the overall organization more coherent. (Should both code grow a lot, we can create a directory to make this a "Guide Section". --- mathics/builtin/lowlevelprofile.py | 56 ------------------- mathics/builtin/trace.py | 89 +++++++++++++++++++++++++----- 2 files changed, 76 insertions(+), 69 deletions(-) delete mode 100644 mathics/builtin/lowlevelprofile.py diff --git a/mathics/builtin/lowlevelprofile.py b/mathics/builtin/lowlevelprofile.py deleted file mode 100644 index 033a2d4f4..000000000 --- a/mathics/builtin/lowlevelprofile.py +++ /dev/null @@ -1,56 +0,0 @@ -# -*- coding: utf-8 -*- - -""" -Low-level Profiling - -Low-level (Python) profile from inside the Mathics3 interpreter - -""" - -import cProfile -import pstats -import sys -from io import StringIO - -from mathics.builtin.base import Builtin -from mathics.core.attributes import A_HOLD_ALL_COMPLETE, A_PROTECTED -from mathics.core.convert.python import from_python -from mathics.core.evaluation import Evaluation -from mathics.core.expression import Expression -from mathics.core.list import ListExpression -from mathics.core.symbols import SymbolNull - - -class PythonCProfileEvaluation(Builtin): - """ - :Python:https://docs.python.org/3/library/profile.html - -
-
'PythonProfileEvaluation[$expr$]' -
profile $expr$ with the Python's cProfiler. -
- - >> PythonCProfileEvaluation[a + b + 1] - = ... - """ - - attributes = A_HOLD_ALL_COMPLETE | A_PROTECTED - summary_text = "profile the internal evaluation of an expression" - - def eval(self, expr: Expression, evaluation: Evaluation): - "PythonCProfileEvaluation[expr_]" - profile_result = SymbolNull - textstream = StringIO() - if sys.version_info >= (3, 8): - with cProfile.Profile() as pr: - result = expr.evaluate(evaluation) - stats = pstats.Stats(pr, stream=textstream) - stats.strip_dirs().sort_stats(-1).print_stats() - # TODO: convert the string (or the statistics) - # into something like a WL Table, by splitting the - # rows and the columns. By now, just a string - # is returned. - profile_result = from_python(textstream.getvalue()) - else: - result = expr.evaluate(evaluation) - return ListExpression(result, profile_result) diff --git a/mathics/builtin/trace.py b/mathics/builtin/trace.py index 3cca7c8c4..759c4df31 100644 --- a/mathics/builtin/trace.py +++ b/mathics/builtin/trace.py @@ -1,25 +1,34 @@ # -*- coding: utf-8 -*- """ -Tracing Built-in Functions +Tracing and Profiling -Built-in Function Tracing provides one high-level way understand what is \ +The 'Trace' builtins provide a Mathics3-oriented trace of what is \ getting evaluated and where the time is spent in evaluation. With this, it may be possible for both users and implementers to follow \ how Mathics3 arrives at its results, or guide how to speed up expression \ evaluation. + +Python :CProfile:https://docs.python.org/3/library/profile.html \ +profiling is available via 'PythonCProfileEvaluation'. """ +import cProfile +import pstats +import sys from collections import defaultdict +from io import StringIO from time import time from typing import Callable from mathics.builtin.base import Builtin -from mathics.core.attributes import A_HOLD_ALL, A_PROTECTED -from mathics.core.convert.python import from_bool +from mathics.core.attributes import A_HOLD_ALL, A_HOLD_ALL_COMPLETE, A_PROTECTED +from mathics.core.convert.python import from_bool, from_python from mathics.core.definitions import Definitions from mathics.core.evaluation import Evaluation +from mathics.core.expression import Expression +from mathics.core.list import ListExpression from mathics.core.rules import BuiltinRule from mathics.core.symbols import SymbolFalse, SymbolNull, SymbolTrue, strip_context @@ -110,7 +119,8 @@ class PrintTrace(_TraceBase): Note that in a browser the information only appears in a console. - If '$TraceBuiltins' was never set to 'True', this will print an empty list. + Note: before '$TraceBuiltins' is set to 'True', 'PrintTrace[]' will print an empty + list. >> PrintTrace[] >> $TraceBuiltins = True @@ -158,7 +168,12 @@ class TraceBuiltins(_TraceBase): >> TraceBuiltins[Graphics3D[Tetrahedron[]]] = -Graphics3D- - By default, the output is sorted by the number of calls of the builtin from highest to lowest: + By default, the output is sorted by the name: + >> TraceBuiltins[Times[x, x]] + = x ^ 2 + + By default, the output is sorted by the number of calls of the builtin from \ + highest to lowest: >> TraceBuiltins[Times[x, x], SortBy->"count"] = x ^ 2 @@ -189,17 +204,26 @@ def dump_tracing_stats(sort_by: str, evaluation) -> None: sort_by = "count" print() + def sort_by_count(tup: tuple): + return tup[1]["count"] + + def sort_by_time(tup: tuple): + return tup[1]["elapsed_milliseconds"] + + def sort_by_name(tup: tuple): + return tup[0] + print("count ms Builtin name") if sort_by == "count": inverse = True - sort_fn = lambda tup: tup[1]["count"] + sort_fn = sort_by_count elif sort_by == "time": inverse = True - sort_fn = lambda tup: tup[1]["elapsed_milliseconds"] + sort_fn = sort_by_time else: inverse = False - sort_fn = lambda tup: tup[0] + sort_fn = sort_by_name for name, statistic in sorted( TraceBuiltins.function_stats.items(), @@ -260,9 +284,12 @@ class TraceBuiltinsVariable(Builtin):
A Boolean Built-in variable when True collects function evaluation statistics. - Setting this variable True will enable statistics collection for Built-in functions that are evaluated. - In contrast to 'TraceBuiltins[]' statistics are accumulated and over several inputs, and are not shown after each input is evaluated. - By default this setting is False. + Setting this variable True will enable statistics collection for Built-in \ + functions that are evaluated. + In contrast to 'TraceBuiltins[]' statistics are accumulated and over several \ + inputs,and are not shown after each input is evaluated. + + By default, this setting is False. >> $TraceBuiltins = True = True @@ -271,7 +298,8 @@ class TraceBuiltinsVariable(Builtin): #> $TraceBuiltins = False = False - Tracing is enabled, so the expressions entered and evaluated will have statistics collected for the evaluations. + Tracing is enabled, so the expressions entered and evaluated will have statistics \ + collected for the evaluations. >> x = x @@ -407,3 +435,38 @@ def eval_set(self, value, evaluation: Evaluation): evaluation.message("$TraceEvaluation", "bool", value) return value + + +class PythonCProfileEvaluation(Builtin): + """ + :Python:https://docs.python.org/3/library/profile.html + +
+
'PythonProfileEvaluation[$expr$]' +
profile $expr$ with the Python's cProfiler. +
+ + >> PythonCProfileEvaluation[a + b + 1] + = ... + """ + + attributes = A_HOLD_ALL_COMPLETE | A_PROTECTED + summary_text = "profile the internal evaluation of an expression" + + def eval(self, expr: Expression, evaluation: Evaluation): + "PythonCProfileEvaluation[expr_]" + profile_result = SymbolNull + textstream = StringIO() + if sys.version_info >= (3, 8): + with cProfile.Profile() as pr: + result = expr.evaluate(evaluation) + stats = pstats.Stats(pr, stream=textstream) + stats.strip_dirs().sort_stats(-1).print_stats() + # TODO: convert the string (or the statistics) + # into something like a WL Table, by splitting the + # rows and the columns. By now, just a string + # is returned. + profile_result = from_python(textstream.getvalue()) + else: + result = expr.evaluate(evaluation) + return ListExpression(result, profile_result) From 28b8f0b137f2aa3c92897938a28a96b6e7c1e713 Mon Sep 17 00:00:00 2001 From: rocky Date: Mon, 10 Jul 2023 16:43:43 -0400 Subject: [PATCH 3/7] More links --- mathics/builtin/drawing/graphics3d.py | 122 +++++++++++++------------- mathics/builtin/drawing/plot.py | 19 ++-- mathics/builtin/image/__init__.py | 4 +- mathics/builtin/optiondoc.py | 11 ++- mathics/builtin/options.py | 6 +- 5 files changed, 91 insertions(+), 71 deletions(-) diff --git a/mathics/builtin/drawing/graphics3d.py b/mathics/builtin/drawing/graphics3d.py index 38ef5db56..5244b6dda 100644 --- a/mathics/builtin/drawing/graphics3d.py +++ b/mathics/builtin/drawing/graphics3d.py @@ -63,66 +63,68 @@ def get_default_face_color(self): class Graphics3D(Graphics): r""" - :WMA link:https://reference.wolfram.com/language/ref/Graphics3D.html - -
-
'Graphics3D[$primitives$, $options$]' -
represents a three-dimensional graphic. - -
See also the Section "Plotting" for a list of Plot options. -
- - >> Graphics3D[Polygon[{{0,0,0}, {0,1,1}, {1,0,0}}]] - = -Graphics3D- - - In 'TeXForm', 'Graphics3D' creates Asymptote figures: - >> Graphics3D[Sphere[]] // TeXForm - = #<--# - . \begin{asy} - . import three; - . import solids; - . size(6.6667cm, 6.6667cm); - . currentprojection=perspective(2.6,-4.8,4.0); - . currentlight=light(rgb(0.5,0.5,1), specular=red, (2,0,2), (2,2,2), (0,2,2)); - . // Sphere3DBox - . draw(surface(sphere((0, 0, 0), 1)), rgb(1,1,1)+opacity(1)); - . draw(((-1,-1,-1)--(1,-1,-1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); - . draw(((-1,1,-1)--(1,1,-1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); - . draw(((-1,-1,1)--(1,-1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); - . draw(((-1,1,1)--(1,1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); - . draw(((-1,-1,-1)--(-1,1,-1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); - . draw(((1,-1,-1)--(1,1,-1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); - . draw(((-1,-1,1)--(-1,1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); - . draw(((1,-1,1)--(1,1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); - . draw(((-1,-1,-1)--(-1,-1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); - . draw(((1,-1,-1)--(1,-1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); - . draw(((-1,1,-1)--(-1,1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); - . draw(((1,1,-1)--(1,1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); - . \end{asy} - - #> Graphics3D[Point[Table[{Sin[t], Cos[t], 0}, {t, 0, 2. Pi, Pi / 15.}]]] // TeXForm - = #<--# - . \begin{asy} - . import three; - . import solids; - . size(6.6667cm, 6.6667cm); - . currentprojection=perspective(2.6,-4.8,4.0); - . currentlight=light(rgb(0.5,0.5,1), specular=red, (2,0,2), (2,2,2), (0,2,2)); - . // Point3DBox - . path3 g=(0,1,0)--(0.20791,0.97815,0)--(0.40674,0.91355,0)--(0.58779,0.80902,0)--(0.74314,0.66913,0)--(0.86603,0.5,0)--(0.95106,0.30902,0)--(0.99452,0.10453,0)--(0.99452,-0.10453,0)--(0.95106,-0.30902,0)--(0.86603,-0.5,0)--(0.74314,-0.66913,0)--(0.58779,-0.80902,0)--(0.40674,-0.91355,0)--(0.20791,-0.97815,0)--(5.6655e-16,-1,0)--(-0.20791,-0.97815,0)--(-0.40674,-0.91355,0)--(-0.58779,-0.80902,0)--(-0.74314,-0.66913,0)--(-0.86603,-0.5,0)--(-0.95106,-0.30902,0)--(-0.99452,-0.10453,0)--(-0.99452,0.10453,0)--(-0.95106,0.30902,0)--(-0.86603,0.5,0)--(-0.74314,0.66913,0)--(-0.58779,0.80902,0)--(-0.40674,0.91355,0)--(-0.20791,0.97815,0)--(1.5314e-15,1,0)--cycle;dot(g, rgb(0, 0, 0)); - . draw(((-0.99452,-1,-1)--(0.99452,-1,-1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); - . draw(((-0.99452,1,-1)--(0.99452,1,-1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); - . draw(((-0.99452,-1,1)--(0.99452,-1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); - . draw(((-0.99452,1,1)--(0.99452,1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); - . draw(((-0.99452,-1,-1)--(-0.99452,1,-1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); - . draw(((0.99452,-1,-1)--(0.99452,1,-1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); - . draw(((-0.99452,-1,1)--(-0.99452,1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); - . draw(((0.99452,-1,1)--(0.99452,1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); - . draw(((-0.99452,-1,-1)--(-0.99452,-1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); - . draw(((0.99452,-1,-1)--(0.99452,-1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); - . draw(((-0.99452,1,-1)--(-0.99452,1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); - . draw(((0.99452,1,-1)--(0.99452,1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); - . \end{asy} + :WMA link:https://reference.wolfram.com/language/ref/Graphics3D.html + +
+
'Graphics3D[$primitives$, $options$]' +
represents a three-dimensional graphic. + + See also the :Drawing Option and Option Values: + /doc/reference-of-built-in-symbols/drawing-options-and-option-values + for a list of Plot options. +
+ + >> Graphics3D[Polygon[{{0,0,0}, {0,1,1}, {1,0,0}}]] + = -Graphics3D- + + In 'TeXForm', 'Graphics3D' creates Asymptote figures: + >> Graphics3D[Sphere[]] // TeXForm + = #<--# + . \begin{asy} + . import three; + . import solids; + . size(6.6667cm, 6.6667cm); + . currentprojection=perspective(2.6,-4.8,4.0); + . currentlight=light(rgb(0.5,0.5,1), specular=red, (2,0,2), (2,2,2), (0,2,2)); + . // Sphere3DBox + . draw(surface(sphere((0, 0, 0), 1)), rgb(1,1,1)+opacity(1)); + . draw(((-1,-1,-1)--(1,-1,-1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); + . draw(((-1,1,-1)--(1,1,-1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); + . draw(((-1,-1,1)--(1,-1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); + . draw(((-1,1,1)--(1,1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); + . draw(((-1,-1,-1)--(-1,1,-1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); + . draw(((1,-1,-1)--(1,1,-1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); + . draw(((-1,-1,1)--(-1,1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); + . draw(((1,-1,1)--(1,1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); + . draw(((-1,-1,-1)--(-1,-1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); + . draw(((1,-1,-1)--(1,-1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); + . draw(((-1,1,-1)--(-1,1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); + . draw(((1,1,-1)--(1,1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); + . \end{asy} + + #> Graphics3D[Point[Table[{Sin[t], Cos[t], 0}, {t, 0, 2. Pi, Pi / 15.}]]] // TeXForm + = #<--# + . \begin{asy} + . import three; + . import solids; + . size(6.6667cm, 6.6667cm); + . currentprojection=perspective(2.6,-4.8,4.0); + . currentlight=light(rgb(0.5,0.5,1), specular=red, (2,0,2), (2,2,2), (0,2,2)); + . // Point3DBox + . path3 g=(0,1,0)--(0.20791,0.97815,0)--(0.40674,0.91355,0)--(0.58779,0.80902,0)--(0.74314,0.66913,0)--(0.86603,0.5,0)--(0.95106,0.30902,0)--(0.99452,0.10453,0)--(0.99452,-0.10453,0)--(0.95106,-0.30902,0)--(0.86603,-0.5,0)--(0.74314,-0.66913,0)--(0.58779,-0.80902,0)--(0.40674,-0.91355,0)--(0.20791,-0.97815,0)--(5.6655e-16,-1,0)--(-0.20791,-0.97815,0)--(-0.40674,-0.91355,0)--(-0.58779,-0.80902,0)--(-0.74314,-0.66913,0)--(-0.86603,-0.5,0)--(-0.95106,-0.30902,0)--(-0.99452,-0.10453,0)--(-0.99452,0.10453,0)--(-0.95106,0.30902,0)--(-0.86603,0.5,0)--(-0.74314,0.66913,0)--(-0.58779,0.80902,0)--(-0.40674,0.91355,0)--(-0.20791,0.97815,0)--(1.5314e-15,1,0)--cycle;dot(g, rgb(0, 0, 0)); + . draw(((-0.99452,-1,-1)--(0.99452,-1,-1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); + . draw(((-0.99452,1,-1)--(0.99452,1,-1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); + . draw(((-0.99452,-1,1)--(0.99452,-1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); + . draw(((-0.99452,1,1)--(0.99452,1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); + . draw(((-0.99452,-1,-1)--(-0.99452,1,-1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); + . draw(((0.99452,-1,-1)--(0.99452,1,-1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); + . draw(((-0.99452,-1,1)--(-0.99452,1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); + . draw(((0.99452,-1,1)--(0.99452,1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); + . draw(((-0.99452,-1,-1)--(-0.99452,-1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); + . draw(((0.99452,-1,-1)--(0.99452,-1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); + . draw(((-0.99452,1,-1)--(-0.99452,1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); + . draw(((0.99452,1,-1)--(0.99452,1,1)), rgb(0.4, 0.4, 0.4)+linewidth(1)); + . \end{asy} """ summary_text = "a three-dimensional graphics image wrapper" options = Graphics.options.copy() diff --git a/mathics/builtin/drawing/plot.py b/mathics/builtin/drawing/plot.py index 80c79cbc6..d641cfa06 100644 --- a/mathics/builtin/drawing/plot.py +++ b/mathics/builtin/drawing/plot.py @@ -2560,15 +2560,24 @@ class Plot3D(_Plot3D): :WMA link: https://reference.wolfram.com/language/ref/Plot3D.html
'Plot3D[$f$, {$x$, $xmin$, $xmax$}, {$y$, $ymin$, $ymax$}]' -
creates a three-dimensional plot of $f$ with $x$ ranging from $xmin$ to $xmax$ and $y$ ranging from $ymin$ to $ymax$. +
creates a three-dimensional plot of $f$ with $x$ ranging from $xmin$ to \ + $xmax$ and $y$ ranging from $ymin$ to $ymax$.
- Plot3D has the same options as Graphics3D, in particular: + Plot3D has the same options as :Graphics3D: +/doc/reference-of-built-in-symbols/graphics-and-drawing/three-dimensional-graphics/graphics3d,\ + in particular:
    -
  • Mesh -
  • PlotPoints -
  • MaxRecursion +
  • + :Mesh: + /doc/reference-of-built-in-symbols/drawing-options-and-option-values/mesh +
  • + :PlotPoints: + /doc/reference-of-built-in-symbols/drawing-options-and-option-values/plotpoints +
  • + :MaxRecursion: + /doc/reference-of-built-in-symbols/drawing-options-and-option-values/maxrecursion
diff --git a/mathics/builtin/image/__init__.py b/mathics/builtin/image/__init__.py index 63ccbaae0..c71d944f7 100644 --- a/mathics/builtin/image/__init__.py +++ b/mathics/builtin/image/__init__.py @@ -2,5 +2,7 @@ Image Manipulation -For the full compliment of functions, you need to have scikit-image installed. +For the full compliment of functions, you need to have :scikit-image: +https://scikit-image.org/ +installed. """ diff --git a/mathics/builtin/optiondoc.py b/mathics/builtin/optiondoc.py index 09331bced..e4db6c5fb 100644 --- a/mathics/builtin/optiondoc.py +++ b/mathics/builtin/optiondoc.py @@ -200,7 +200,8 @@ class MaxRecursion(Builtin):
'MaxRecursion' -
is an option for functions like NIntegrate and Plot that specifies how many recursive subdivisions can be made. +
is an option for functions like NIntegrate and Plot that specifies how many \ + recursive subdivisions can be made.
>> NIntegrate[Exp[-10^8 x^2], {x, -1, 1}, Method->"Internal", MaxRecursion -> 3] @@ -209,7 +210,10 @@ class MaxRecursion(Builtin): = 0.00972222 """ - summary_text = "function option specifying the maximum number of recursive subdivisions the function can perform" + summary_text = ( + "function option specifying the maximum number of recursive " + "subdivisions the function can perform" + ) class Mesh(Builtin): @@ -218,7 +222,8 @@ class Mesh(Builtin):
'Mesh' -
is a charting option, such as for 'Plot', 'BarChart', 'PieChart', etc. that specifies the mesh to be drawn. The default is 'Mesh->None'. +
is a charting option, such as for 'Plot', 'BarChart', 'PieChart', etc. that \ + specifies the mesh to be drawn. The default is 'Mesh->None'.
>> Plot[Sin[Cos[x^2]],{x,-4,4},Mesh->All] diff --git a/mathics/builtin/options.py b/mathics/builtin/options.py index e3d314de8..5c52e5459 100644 --- a/mathics/builtin/options.py +++ b/mathics/builtin/options.py @@ -39,7 +39,8 @@ class All(Predefined): For example, in :Part: /doc/reference-of-built-in-symbols/list-functions/elements-of-lists/part, \ - 'All', extracts into a first column vector the first element of each of the list elements: + 'All', extracts into a first column vector the first element of each of the \ + list elements: >> {{1, 3}, {5, 7}}[[All, 1]] = {1, 5} @@ -47,7 +48,8 @@ class All(Predefined): While in :Take: /doc/reference-of-built-in-symbols/list-functions/elements-of-lists/part, \ - 'All' extracts as a column matrix the first element as a list for each of the list elements: + 'All' extracts as a column matrix the first element as a list for each of the list \ + elements: >> Take[{{1, 3}, {5, 7}}, All, {1}] = {{1}, {5}} From f18ebbdf280df5832e1b4bc7f24342182fd77318 Mon Sep 17 00:00:00 2001 From: rocky Date: Tue, 11 Jul 2023 02:35:22 -0400 Subject: [PATCH 4/7] Preserve summary text to non-guide Django sections Also start regularizing section summary text here. --- mathics/builtin/graphics.py | 46 ++++++++++++++++++++---------------- mathics/builtin/layout.py | 2 +- mathics/builtin/optiondoc.py | 28 ++++++++++++---------- mathics/doc/common_doc.py | 9 +++++-- 4 files changed, 50 insertions(+), 35 deletions(-) diff --git a/mathics/builtin/graphics.py b/mathics/builtin/graphics.py index ea8588b32..f1ba9993b 100644 --- a/mathics/builtin/graphics.py +++ b/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,7 +592,8 @@ 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- @@ -600,7 +601,7 @@ class Polygon(Builtin): = -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):
represents a line with arrow that keeps a distance of $s$ from $p1$ and $p2$.
'Arrow[{$point_1$, $point_2$}, {$s1$, $s2$}]' -
represents a line with arrow that keeps a distance of $s1$ from $p1$ and a distance of $s2$ from $p2$. +
represents a line with arrow that keeps a distance of $s1$ from $p1$ and a \ + distance of $s2$ from $p2$.
'Arrow[{$point_1$, $point_2$}, {$s1$, $s2$}]' -
represents a line with arrow that keeps a distance of $s1$ from $p1$ and a distance of $s2$ from $p2$. +
represents a line with arrow that keeps a distance of $s1$ from $p1$ and a \ + distance of $s2$ from $p2$. >> 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):
'Arrowheads[$s$]' -
specifies that Arrow[] draws one arrow of size $s$ (relative to width of image, defaults to 0.04). +
specifies that Arrow[] draws one arrow of size $s$ (relative to width of \ + image, defaults to 0.04).
'Arrowheads[{$spec1$, $spec2$, ..., $specn$}]' -
specifies that Arrow[] draws n arrows as defined by $spec1$, $spec2$, ... $specn$. +
specifies that Arrow[] draws n arrows as defined by $spec1$, $spec2$, \ + ... $specn$.
'Arrowheads[{{$s$}}]'
specifies that one arrow of size $s$ should be drawn.
'Arrowheads[{{$s$, $pos$}}]' -
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). +
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).
'Arrowheads[{{$s$, $pos$, $g$}}]' -
specifies that one arrow of size $s$ should be drawn at position $pos$ using Graphics $g$. +
specifies that one arrow of size $s$ should be drawn at position $pos$ \ + using Graphics $g$.
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) diff --git a/mathics/builtin/layout.py b/mathics/builtin/layout.py index 7d01543f9..0397b09b3 100644 --- a/mathics/builtin/layout.py +++ b/mathics/builtin/layout.py @@ -420,7 +420,7 @@ class Style(Builtin): """ - summary_text = "wrapper specifying styles and style options to apply" + summary_text = "wrapper for styles and style options to apply" options = {"ImageSizeMultipliers": "Automatic"} rules = { diff --git a/mathics/builtin/optiondoc.py b/mathics/builtin/optiondoc.py index e4db6c5fb..a4d3592f1 100644 --- a/mathics/builtin/optiondoc.py +++ b/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):
'ChartLabels' -
is a charting option that specifies what labels should be used for chart elements. +
is a charting option that specifies what labels should be used for chart \ + elements.
>> 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):
'ChartLegends' -
is an option for charting functions that specifies the legends to be used for chart elements. +
is an option for charting functions that specifies the legends to be used \ + for chart elements.
""" - 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):
'TicksStyle' -
is an option for graphics functions which specifies how ticks should be rendered. +
is an option for graphics functions which specifies how ticks should be \ + rendered.