source: sasmodels/sasmodels/rst2html.py @ 6592f56

core_shell_microgelscostrafo411magnetic_modelrelease_v0.94release_v0.95ticket-1257-vesicle-productticket_1156ticket_1265_superballticket_822_more_unit_tests
Last change on this file since 6592f56 was 6592f56, checked in by Paul Kienzle <pkienzle@…>, 5 years ago

view plugin model docs from sasview console

  • Property mode set to 100644
File size: 5.5 KB
Line 
1r"""
2Convert a restructured text document to html.
3
4Inline math markup can uses the *math* directive, or it can use latex
5style *\$expression\$*.  Math can be rendered using simple html and
6unicode, or with mathjax.
7"""
8
9import re
10from contextlib import contextmanager
11
12# CRUFT: locale.getlocale() fails on some versions of OS X
13# See https://bugs.python.org/issue18378
14import locale
15if hasattr(locale, '_parse_localename'):
16    try:
17        locale._parse_localename('UTF-8')
18    except ValueError:
19        _old_parse_localename = locale._parse_localename
20        def _parse_localename(localename):
21            code = locale.normalize(localename)
22            if code == 'UTF-8':
23                return None, code
24            else:
25                return _old_parse_localename(localename)
26        locale._parse_localename = _parse_localename
27
28from docutils.core import publish_parts
29from docutils.writers.html4css1 import HTMLTranslator
30from docutils.nodes import SkipNode
31
32def wxview(html, url="", size=(850, 540)):
33    import wx
34    from wx.html2 import WebView
35    frame = wx.Frame(None, -1, size=size)
36    view = WebView.New(frame)
37    view.SetPage(html, url)
38    frame.Show()
39    return frame
40
41def view_rst(filename):
42    from os.path import expanduser
43    with open(expanduser(filename)) as fid:
44        rst = fid.read()
45    html = rst2html(rst)
46    wxview(html)
47
48def rst2html(rst, part="whole", math_output="mathjax"):
49    r"""
50    Convert restructured text into simple html.
51
52    Valid *math_output* formats for formulas include:
53    - html
54    - mathml
55    - mathjax
56    See `http://docutils.sourceforge.net/docs/user/config.html#math-output`_
57    for details.
58
59    The following *part* choices are available:
60    - whole: the entire html document
61    - html_body: document division with title and contents and footer
62    - body: contents only
63
64    There are other parts, but they don't make sense alone:
65
66        subtitle, version, encoding, html_prolog, header, meta,
67        html_title, title, stylesheet, html_subtitle, html_body,
68        body, head, body_suffix, fragment, docinfo, html_head,
69        head_prefix, body_prefix, footer, body_pre_docinfo, whole
70    """
71    # Ick! mathjax doesn't work properly with math-output, and the
72    # others don't work properly with math_output!
73    if math_output == "mathjax":
74        settings = {"math_output": math_output}
75    else:
76        settings = {"math-output": math_output}
77
78    # TODO: support stylesheets
79    #html_root = "/full/path/to/_static/"
80    #sheets = [html_root+s for s in ["basic.css","classic.css"]]
81    #settings["embed_styesheet"] = True
82    #settings["stylesheet_path"] = sheets
83
84    # math2html and mathml do not support \frac12
85    rst = replace_compact_fraction(rst)
86
87    # mathml, html do not support \tfrac
88    if math_output in ("mathml", "html"):
89        rst = rst.replace(r'\tfrac', r'\frac')
90
91    rst = replace_dollar(rst)
92    with suppress_html_errors():
93        parts = publish_parts(source=rst, writer_name='html',
94                              settings_overrides=settings)
95    return parts[part]
96
97@contextmanager
98def suppress_html_errors():
99    r"""
100    Context manager for keeping error reports out of the generated HTML.
101
102    Within the context, system message nodes in the docutils parse tree
103    will be ignored.  After the context, the usual behaviour will be restored.
104    """
105    visit_system_message = HTMLTranslator.visit_system_message
106    HTMLTranslator.visit_system_message = _skip_node
107    yield None
108    HTMLTranslator.visit_system_message = visit_system_message
109
110def _skip_node(self, node):
111    raise SkipNode
112
113
114_compact_fraction = re.compile(r"(\\[cdt]?frac)([0-9])([0-9])")
115def replace_compact_fraction(content):
116    r"""
117    Convert \frac12 to \frac{1}{2} for broken latex parsers
118    """
119    return _compact_fraction.sub(r"\1{\2}{\3}", content)
120
121
122_dollar = re.compile(r"(?:^|(?<=\s|[(]))[$]([^\n]*?)(?<![\\])[$](?:$|(?=\s|[.,;)\\]))")
123_notdollar = re.compile(r"\\[$]")
124def replace_dollar(content):
125    r"""
126    Convert dollar signs to inline math markup in rst.
127    """
128    content = _dollar.sub(r":math:`\1`", content)
129    content = _notdollar.sub("$", content)
130    return content
131
132
133def test_dollar():
134    """
135    Test substitution of dollar signs with equivalent RST math markup
136    """
137    assert replace_dollar(u"no dollar") == u"no dollar"
138    assert replace_dollar(u"$only$") == u":math:`only`"
139    assert replace_dollar(u"$first$ is good") == u":math:`first` is good"
140    assert replace_dollar(u"so is $last$") == u"so is :math:`last`"
141    assert replace_dollar(u"and $mid$ too") == u"and :math:`mid` too"
142    assert replace_dollar(u"$first$, $mid$, $last$") == u":math:`first`, :math:`mid`, :math:`last`"
143    assert replace_dollar(ur"dollar\$ escape") == u"dollar$ escape"
144    assert replace_dollar(ur"dollar \$escape\$ too") == u"dollar $escape$ too"
145    assert replace_dollar(u"spaces $in the$ math") == u"spaces :math:`in the` math"
146    assert replace_dollar(ur"emb\ $ed$\ ed") == ur"emb\ :math:`ed`\ ed"
147    assert replace_dollar(u"$first$a") == u"$first$a"
148    assert replace_dollar(u"a$last$") == u"a$last$"
149    assert replace_dollar(u"$37") == u"$37"
150    assert replace_dollar(u"($37)") == u"($37)"
151    assert replace_dollar(u"$37 - $43") == u"$37 - $43"
152    assert replace_dollar(u"($37, $38)") == u"($37, $38)"
153    assert replace_dollar(u"a $mid$dle a") == u"a $mid$dle a"
154    assert replace_dollar(u"a ($in parens$) a") == u"a (:math:`in parens`) a"
155    assert replace_dollar(u"a (again $in parens$) a") == u"a (again :math:`in parens`) a"
156
157if __name__ == "__main__":
158    test_dollar()
Note: See TracBrowser for help on using the repository browser.