Ticket #6673: trac_6673-jsmath_macros_docs_v3.patch

MANIFEST.in

@@ -33 +33 @@
 include doc/en/bordeaux_2008/modpcurve.png
 recursive-include doc/en/reference/media *
 recursive-include doc/common/static *
+recursive-include doc/common/themes *

doc/common/conf.py

@@ -18 +18 @@
     extensions.append('sphinx.ext.jsmath')
 else:
     extensions.append('sphinx.ext.pngmath')
-jsmath_path = 'easy/load.js'
+jsmath_path = 'jsmath_sage.js'
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = [os.path.join(SAGE_DOC, 'common/templates'), 'templates']
@@ -76 +76 @@
 # output. They are ignored by default.
 #show_authors = False
 
-# The name of the Pygments (syntax highlighting) style to use.
+# The name of the Pygments (syntax highlighting) style to use.  NOTE:
+# This overrides a HTML theme's corresponding setting (see below).
 pygments_style = 'sphinx'
 
 
 # Options for HTML output
 # -----------------------
 
-# The style sheet to use for HTML and HTML Help pages. A file of that name
-# must exist either in Sphinx' static/ path, or in one of the custom paths
-# given in html_static_path.
-html_style = 'default.css'
+# HTML theme (e.g., 'default', 'sphinxdoc').  We use a custom Sage
+# theme to set a Pygments style, stylesheet, and insert jsMath macros.
+html_theme = 'sage'
+
+# Theme options are theme-specific and customize the look and feel of
+# a theme further.  For a list of options available for each theme,
+# see the documentation.
+html_theme_options = {}
+
+if 'SAGE_DOC_JSMATH' in os.environ:
+    from sage.misc.latex_macros import sage_jsmath_macros_easy
+    html_theme_options['jsmath_macros'] = sage_jsmath_macros_easy
+
+    from sage.misc.package import is_package_installed
+    html_theme_options['jsmath_image_fonts'] = is_package_installed('jsmath-image-fonts')
+
+# Add any paths that contain custom themes here, relative to this directory.
+html_theme_path = [os.path.join(SAGE_DOC, 'common/themes')]
+
+# HTML style sheet NOTE: This overrides a HTML theme's corresponding
+# setting.
+#html_style = 'default.css'
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -113 +132 @@
 # array.  We can override / overwrite selected files by putting them
 # in the remaining paths.
 if 'SAGE_DOC_JSMATH' in os.environ:
-    jsmath_static = os.path.join(SAGE_ROOT, 'local/lib/python/site-packages/sagenb/data/javascript/jsmath/')
+    jsmath_static = os.path.join(SAGE_ROOT, 'local/lib/python/site-packages/sagenb/data/jsmath/')
     html_static_path.insert(0, jsmath_static)
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,

layout.html

@@ -1 @@
-{% extends "!layout.html" %}
+{% extends "basic/layout.html" %}
 
 {% block rootrellink %}
-    <img src="{{ pathto('_static/sagelogo.png', 1) }}" style="vertical-align: middle" title="Sage Logo">
-    {{ super() }}
+  {% if docstitle.startswith('Sage Documentation') %}
+    <a href="http://www.sagemath.org"><img src="{{ pathto('_static/sagelogo.png', 1) }}" style="vertical-align: middle" title="Sage Logo"></a>
+  {% else %}
+    {% if pathto(master_doc).endswith('.html') %}
+      <a href="{{ '../' + pathto(master_doc) }}"><img src="{{ pathto('_static/sagelogo.png', 1) }}" style="vertical-align: middle" title="Sage Logo"></a>
+    {% else %}
+      <a href="{{ '../' + pathto(master_doc) + 'index.html' }}"><img src="{{ pathto('_static/sagelogo.png', 1) }}" style="vertical-align: middle" title="Sage Logo"></a>
+    {% endif %}
+  {% endif %}
+  {{ super() }}
 {% endblock %}
 
 {% block extrahead %}

new file doc/common/themes/sage/static/jsmath_sage.js_t

@@ +1 @@
+/**********************************************************************
+ *
+ *   Customize the values given below to suit your needs.
+ *   You can make additional copies of this file with
+ *   different customizated settings if you need to load
+ *   jsMath with different parameters.
+ *
+ *   Load this page via:
+ *
+ *   <SCRIPT SRC="path-to-jsMath/easy/load.js"></SCRIPT>
+ *
+ *   (If you are including this file into your page via Server-Side
+ *   Includes, you should remove line above.)
+ *
+ *   You can make copies of this file with different settings
+ *   if you need to have several different configurations.
+ *
+ **********************************************************************/
+
+    if (!window.jsMath) {window.jsMath = {}}
+
+//  Move the jsMath button 20 pixels from the right edge (apparently
+//  in some browsers, it covers up the scroll bar)
+jsMath.styles = {
+    '#jsMath_button' : 'position:fixed; bottom:1px; right:20px; '
+        + 'background-color:white; border: solid 1px #959595; margin:0px; '
+        + 'padding: 0px 3px 1px 3px; z-index:102; color:black; '
+        + 'text-decoration:none; font-size:x-small; width:auto; cursor:hand;'
+}
+
+jsMath.Easy = {
+    //
+    //  The URL of the root jsMath directory on your server
+    //  (it must be in the same domain as the HTML page).
+    //  It should include "http://yoursite.com/", or should
+    //  be relative to the root of your server.  It is possible
+    //  to be a relative URL, but it will be relative to the
+    //  HTML page loading this file.
+    //
+    //  If you leave this blank, jsMath will try to look it up from
+    //  the URL where it loaded this file, but that may not work.
+    //
+    root: "",
+
+    //
+    //  The default scaling factor for mathematics compared to the
+    //  surrounding text.
+    //
+    scale: 115,
+
+    //
+    //  1 means use the autoload plug-in to decide if jsMath should be loaded
+    //  0 means always load jsMath
+    //
+    autoload: 1,
+
+    //
+    //  Setting any of these will cause the tex2math plugin to be used
+    //  to add the <DIV> and <SPAN> tags that jsMath needs.  See the
+    //  documentation for the tex2math plugin for more information.
+    //
+    processSlashParens: 0,       // process \(...\) in text?
+    processSlashBrackets: 0,     // process \[...\] in text?
+    processDoubleDollars: 0,     // process $$...$$ in text?
+    processSingleDollars: 0,     // process $...$ in text?
+    processLaTeXenvironments: 0, // process \begin{xxx}...\end{xxx} outside math mode?
+    fixEscapedDollars: 0,        // convert \$ to $ outside of math mode?
+    doubleDollarsAreInLine: 0,   // make $$...$$ be in-line math?
+    allowDisableTag: 0,          // allow ID="tex2math_off" to disable tex2math?
+    //
+    //  If you want to use your own custom delimiters for math instead
+    //  of the usual ones, then uncomment the following four lines and
+    //  insert your own delimiters within the quotes.  You may want to
+    //  turn off processing of the dollars and other delimiters above
+    //  as well, though you can use them in combination with the
+    //  custom delimiters if you wish.  See the tex2math documentation
+    //  for more details.
+    //
+    //customDelimiters: [
+    //  '[math]','[/math]',        // to begin and end in-line math
+    //  '[display]','[/display]'   // to begin and end display math
+    //],
+
+    //
+    //  Disallow the use of the @(...) mechanism for including raw HTML
+    //  in the contents of \hbox{}?  (If used in a content-management system
+    //  where users are allowed to enter mathematics, setting this to 0
+    //  would allow them to enter arbitrary HTML code within their
+    //  math formulas, and that poses a security risk.)
+    //
+    safeHBoxes: 1,
+
+    //
+    //  Show TeX source when mathematics is double-clicked?
+    //
+    allowDoubleClicks: 1,
+
+    //
+    //  Show jsMath font warning messages?  (Disabling this prevents yours
+    //  users from finding out that they can have a better experience on your
+    //  site by installing some fonts, so don't disable this).
+    //
+    showFontWarnings: 0,
+
+    //
+    //  Use "Process" or "ProcessBeforeShowing".  See the jsMath
+    //  author's documentation for the difference between these
+    //  two routines.
+    //
+    method: "Process",
+
+    //
+    //  List of plug-ins and extensions that you want to be
+    //  loaded automatically.  E.g.
+    //      ["plugins/mimeTeX.js","extensions/AMSsymbols.js"]
+    //
+    loadFiles: [
+        "extensions/verb.js",
+        "extensions/moreArrows.js",
+        "extensions/AMSmath.js",
+        "extensions/AMSsymbols.js"
+    ],
+
+    //
+    //  List of fonts to load automatically.  E.g.
+    //      ["cmmib10"]
+    //
+    loadFonts: [],
+
+    //
+    //  List of macros to define.  These are of the form
+    //      name: value
+    //  where 'value' is the replacement text for the macro \name.
+    //  The 'value' can also be [value,n] where 'value' is the replacement
+    //  text and 'n' is the number of parameters for the macro.
+    //  Note that backslashes must be doubled in the replacement string.
+    //  E.g.,
+    //      {
+    //        RR: '{\\bf R}',
+    //        bold: ['{\\bf #1}', 1]
+    //      }
+    //
+    // Sage-specific jsMath macros.
+    macros: {
+    {{ theme_jsmath_macros|join(',\n') }}
+    },
+
+    //
+    //  Allow jsMath to enter global mode?
+    //  (Uses frames, so may not always work with complex web sites)
+    //
+    allowGlobal: 1,
+
+    //
+    //  Disable image fonts?  (In case you don't load them on your server.)
+    //
+    // If we set this to 1, we do not need to load plugins/noImageFonts.js
+    {% if theme_jsmath_image_fonts %}
+    noImageFonts: 0
+    {% else %}
+    noImageFonts: 1
+    {% endif %}
+};
+
+/****************************************************************/
+/****************************************************************/
+//
+//            DO NOT MAKE CHANGES BELOW THIS
+//
+/****************************************************************/
+/****************************************************************/
+
+jsMath.Easy.find_root = function () {
+    if (jsMath.Easy.root == "") {
+        jsMath.Easy.root = document.getElementsByTagName("script");
+        for (var i = 0; i < jsMath.Easy.root.length; i++) {
+            if (jsMath.Easy.root[i].src.match(/doctools.js$/)) {
+                jsMath.Easy.root = jsMath.Easy.root[i].src.replace(/doctools.js$/, "");
+                return;
+            }
+        }
+        jsMath.Easy.root = jsMath.Easy.root[jsMath.Easy.root.length-1].src
+        if (jsMath.Easy.root.match(/\/easy\/[^\/]*$/)) {
+            jsMath.Easy.root = jsMath.Easy.root.replace(/\/easy\/[^\/]*$/,"");
+        } else {
+            jsMath.Easy.root = jsMath.Easy.root.replace(/\/(jsMath\/(easy\/)?)?[^\/]*$/,"/jsMath");
+        }
+    }
+};
+
+jsMath.Easy.find_root();
+
+jsMath.Easy.root = jsMath.Easy.root.replace(/\/$/,""); // trim trailing "/" if any
+
+document.write('<SCRIPT SRC="'+jsMath.Easy.root+'/jsMath-easy-load.js"><'+'/SCRIPT>');

new file doc/common/themes/sage/theme.conf

@@ +1 @@
+[theme]
+inherit = default
+stylesheet = default.css
+pygments_style = sphinx
+
+[options]
+# Custom Sage theme options
+
+# jsMath settings filled in by conf.py
+jsmath_macros =
+jsmath_image_fonts =
+
+# Sphinx default theme options
+
+#nosidebar = false
+#rightsidebar = false
+#stickysidebar = false
+
+#footerbgcolor    = #11303d
+#footertextcolor  = #ffffff
+#sidebarbgcolor   = #1c4e63
+#sidebartextcolor = #ffffff
+#sidebarlinkcolor = #98dbcc
+#relbarbgcolor    = #133f52
+#relbartextcolor  = #ffffff
+#relbarlinkcolor  = #ffffff
+#bgcolor          = #ffffff
+#textcolor        = #000000
+#headbgcolor      = #f2f2f2
+#headtextcolor    = #20435c
+#headlinkcolor    = #c60f0f
+#linkcolor        = #355f7c
+#codebgcolor      = #eeffcc
+#codetextcolor    = #333333
+
+#bodyfont = sans-serif
+#headfont = 'Trebuchet MS', sans-serif

sage/misc/latex_macros.py

@@ -118 +118 @@
 
         sage: from sage.misc.latex_macros import convert_latex_macro_to_jsmath
         sage: convert_latex_macro_to_jsmath('\\newcommand{\\ZZ}{\\Bold{Z}}')
-        "jsMath.Macro('ZZ','\\\\Bold{Z}')"
+        "jsMath.Macro('ZZ','\\\\Bold{Z}');"
         sage: convert_latex_macro_to_jsmath('\\newcommand{\\GF}[1]{\\Bold{F}_{#1}}')
-        "jsMath.Macro('GF','\\\\Bold{F}_{#1}',1)"
+        "jsMath.Macro('GF','\\\\Bold{F}_{#1}',1);"
     """
     left_bracket = macro.find('[')
     right_bracket = macro.find('[')
@@ -139 +139 @@
         args_str = "," + str(num_args)
     else:
         args_str = ""
-    return "jsMath.Macro('" + name + "','" + defn + "'" + args_str + ")"
+    return "jsMath.Macro('" + name + "','" + defn + "'" + args_str + ");"
+
+def convert_latex_macro_to_jsmath_easy(macro):
+    r"""
+    This converts a LaTeX macro definition (\newcommand...) to a
+    definition for jsMath's easy/load.js macro array.
+
+    INPUT:
+
+    -  ``macro`` - LaTeX macro definition
+
+    EXAMPLES::
+
+        sage: from sage.misc.latex_macros import convert_latex_macro_to_jsmath_easy
+        sage: convert_latex_macro_to_jsmath_easy('\\newcommand{\\ZZ}{\\Bold{Z}}')
+        "ZZ : '{\\\\Bold{Z}}'"
+        sage: convert_latex_macro_to_jsmath_easy('\\newcommand{\\GF}[1]{\\Bold{F}_{#1}}')
+        "GF : ['{\\\\Bold{F}_{#1}}', 1]"
+    """
+    left_bracket = macro.find('[')
+    right_bracket = macro.find('[')
+    if left_bracket >= 0:
+        right_bracket = macro.find(']')
+        num_args = macro[left_bracket+1:right_bracket]
+    else:
+        num_args = 0
+    start_name = macro.find('{') + 1  # add one to go past the backslash
+    end_name = macro.find('}')
+    name = macro[start_name+1:end_name]
+    start_defn = macro.find('{', end_name)
+    end_defn = macro.rfind('}')
+    defn = macro[start_defn+1: end_defn].replace('\\', '\\\\')
+    if num_args > 0:
+        args_str = "," + str(num_args)
+        return name + " : ['{" + defn + "}', " + str(num_args) + ']'
+    else:
+        return name + " : '{" + defn + "}'"
 
 # To add a new macro for use in the Sage documentation, add a list or
 # tuple to the following list.  Each list (or tuple) should have the
@@ -176 +212 @@
 
 sage_latex_macros += sage_configurable_latex_macros
 
+# jsMath macro definitions as JavaScript, e.g., to include in HTML
+# script elements.
 sage_jsmath_macros = [convert_latex_macro_to_jsmath(m) for m in sage_latex_macros]
+
+# jsMath macro definitions for an easy/load.js file's "macros" array.
+sage_jsmath_macros_easy = [convert_latex_macro_to_jsmath_easy(m) for m in sage_latex_macros]