def main():
# Create a writer to deal with the generic element we may have created.
writer = Writer()
writer.translator_class = MyTranslator
description = (
'Generates (X)HTML documents from standalone reStructuredText '
'sources. Be forgiving against unknown elements. ' +
default_description)
# the parser processes the settings too late: we want to decide earlier if
# we are running or testing.
if ('--test-patch' in sys.argv
and not ('-h' in sys.argv or '--help' in sys.argv)):
return test_patch(writer)
else:
# Make docutils lenient.
patch_docutils()
overrides = {
# If Pygments is missing, code-block directives are swallowed
# with Docutils >= 0.9.
'syntax_highlight': 'none',
# not available on Docutils < 0.8 so can't pass as an option
'math_output': 'HTML',
}
publish_cmdline(writer=writer,
description=description,
settings_spec=LenientSettingsSpecs,
settings_overrides=overrides)
return 0
def rst2html(rst):
from docutils.core import publish_string
from docutils.writers.html4css1 import Writer, HTMLTranslator
class xia2HTMLTranslator(HTMLTranslator):
def __init__(self, document):
HTMLTranslator.__init__(self, document)
def visit_table(self, node):
self.context.append(self.compact_p)
self.compact_p = True
classes = " ".join(["docutils", self.settings.table_style]).strip()
self.body.append(
self.starttag(node, "table", CLASS=classes, border="0"))
def write_colspecs(self):
self.colspecs = []
xia2_root_dir = os.path.dirname(xia2.__file__)
args = {
"stylesheet_path": os.path.join(xia2_root_dir, "css", "voidspace.css")
}
w = Writer()
w.translator_class = xia2HTMLTranslator
return publish_string(rst,
writer=w,
settings=None,
settings_overrides=args)
def render(raw: str,
stream: Optional[IO[str]] = None,
**kwargs: Any) -> Optional[str]:
if stream is None:
# Use a io.StringIO as the warning stream to prevent warnings from
# being printed to sys.stderr.
stream = io.StringIO()
settings = SETTINGS.copy()
settings["warning_stream"] = stream
writer = Writer()
writer.translator_class = ReadMeHTMLTranslator
try:
parts = publish_parts(raw, writer=writer, settings_overrides=settings)
except SystemMessage:
rendered = None
else:
rendered = parts.get("docinfo", "") + parts.get("fragment", "")
if rendered:
return clean(rendered)
else:
# If the warnings stream is empty, docutils had none, so add ours.
if not stream.tell():
stream.write("No content rendered from RST source.")
return None
def rst2odt(rst):
from docutils.core import publish_string
from docutils.writers.odf_odt import Writer
w = Writer()
return publish_string(rst, writer=w)
def render(self):
''' Render the source to HTML
'''
if self._v_formatted is None:
warnings = self._v_warnings = Warnings()
settings = {
'halt_level': 6,
'report_level': int(self.report_level),
'input_encoding': self.input_encoding,
'output_encoding': self.output_encoding,
'initial_header_level': 1,
'stylesheet': self.stylesheet,
'stylesheet_path': None,
'warning_stream': warnings,
'raw_enabled': 0,
'file_insertion_enabled': 0,
}
self._v_formatted = docutils.core.publish_string(
self.source,
writer=Writer(),
settings_overrides=settings,
)
return self._v_formatted
def publishPage(self, key):
src = self.pages[key].rst
pubpath = os.path.join(rootpath, "public", key)
try:
os.makedirs(os.path.split(pubpath)[0])
except:
pass
# Soft reset
traveler.features.reset()
writer = Writer()
writer.translator_class = HTMLTranslatorForLegalResourceRegistry
keylst = key.split("/")
upset = [".."] * (len(keylst) - 1)
css = os.path.sep.join(upset + ["screen.css"])
octicons = os.path.sep.join(
upset + ["bower_components/octicons/octicons/octicons.css"])
options = {
"stylesheet": octicons + "," + css,
"stylesheet_path": None,
"embed_stylesheet": False,
"footnote_backlinks": True,
"input_encoding": "utf-8"
}
src = src + '\n.. raw:: html\n\n </div>\n'
html = publish_string(src,
reader=None,
reader_name='standalone',
writer=writer,
settings_overrides=options)
if self.writePages:
codecs.open(pubpath, "w+", "utf-8").write(html)
def convert_string_RST(myString, use_mathjax=False):
"""
Converts a valid reStructuredText_ input string into rich HTML.
:param str myString: the candidate reStructuredText_ input.
:param bool use_mathjax: if ``True``, then use MathJax_ for math formulae. Default is ``False``.
:returns: If the input string is valid reStructuredText_, returns the rich HTML as a :py:class:`string <str>`. Otherwise emits a :py:meth:`logging error message <logging.error>` and returns ``None``.
:rtype: str
.. seealso:: :py:meth:`check_valid_RST <nprstuff.npremail.check_valid_RST>`.
"""
if not check_valid_RST(myString):
logging.error("Error, could not convert %s into RST." % myString)
return None
overrides = {
'input_encoding': 'unicode',
'doctitle_xform': True,
'initial_header_level': 1
}
if use_mathjax:
overrides['math_output'] = 'mathjax'
htmlwriter = Writer()
htmlwriter.translator_class = MyHTMLTranslator
parts = core.publish_parts(source=myString,
source_path=None,
destination_path=None,
writer_name='html',
writer=htmlwriter,
settings_overrides=overrides)
html_body = parts['whole']
html = BeautifulSoup(html_body, 'lxml')
return html.prettify()
def check_valid_RST(myString, use_mathjax=False):
"""
Checks to see whether the input string is valid reStructuredText_.
:param str myString: the candidate reStructuredText_ input.
:param bool use_mathjax: if ``True``, then use MathJax_ for math formulae. Default is ``False``.
:returns: ``True`` if valid, otherwise ``False``.
:rtype: bool
.. seealso:: :py:meth:`convert_string_RST <nprstuff.npremail.convert_string_RST>`.
.. _MathJax: https://www.mathjax.org
"""
overrides = {
'input_encoding': 'unicode',
'doctitle_xform': True,
'initial_header_level': 1
}
if use_mathjax:
overrides['math_output'] = 'mathjax'
htmlwriter = Writer()
htmlwriter.translator_class = MyHTMLTranslator
parts = core.publish_parts(source=myString,
source_path=None,
destination_path=None,
writer_name='html',
writer=htmlwriter,
settings_overrides=overrides)
body = parts['body']
html = BeautifulSoup(body, 'lxml')
error_messages = html.find_all('p', {'class': 'system-message-title'})
return len(error_messages) == 0
def render_rst(rst_filename):
class HTMLFragmentTranslator(HTMLTranslator):
def __init__(self, document):
HTMLTranslator.__init__(self, document)
self.head_prefix = ['', '', '', '', '']
self.body_prefix = []
self.body_suffix = []
self.stylesheet = []
def astext(self):
return ''.join(self.body)
html_fragment_writer = Writer()
html_fragment_writer.translator_class = HTMLFragmentTranslator
def rest_to_html(s):
result = core.publish_string(s, writer=html_fragment_writer)
result = result.decode('utf8')
root = lxml.html.fromstring(result)
nodes = root.xpath('//div[@class="document"]')
assert len(nodes) == 1
return lxml.html.tostring(nodes[0], encoding=str)
if not rst_filename:
return u''
elif rst_filename.endswith('.rst'):
fn = os.path.join(os.path.dirname(__file__), 'content', rst_filename)
if not os.path.exists(fn):
raise IOError('RST file {} not found'.format(fn))
with open(fn) as fp:
rst_data = fp.read()
return rest_to_html(rst_data)
else:
return rest_to_html(rst_filename)
def rst_to_html(rst_string, settings=None):
"""Convert a string written in reStructuredText to an HTML string.
:param rst_string:
A string that holds the contents of a reStructuredText document.
:param settings:
Optional. A dictionary which overrides the default settings.
For a list of the possible keys and values, see
http://docutils.sourceforge.net/docs/user/config.html.
To log the values used, pass in ``'dump_settings': 'yes'``.
"""
writer = Writer()
writer.translator_class = HTMLTranslator
if settings is None:
settings = {
# Include a time/datestamp in the document footer.
'datestamp': '%Y-%m-%d %H:%M UTC',
# Recognize and link to standalone PEP references (like "PEP 258").
'pep_references': 1,
# Do not report any system messages.
'report_level': 'none',
# Recognize and link to standalone RFC references (like "RFC 822").
'rfc_references': 1,
}
return core.publish_string(rst_string,
writer=writer,
settings_overrides=settings)
def _render_html(source):
return core.publish_parts(
source=source,
writer=Writer(),
writer_name='html',
settings_overrides={'no_system_messages': True}
)
def rst2latex(rst):
from docutils.core import publish_string
from docutils.writers.latex2e import Writer
w = Writer()
return publish_string(rst, writer=w)
def render_rest(content):
# start by h2 and ignore invalid directives and so on
# (most likely from Sphinx)
settings = {'initial_header_level': 2, 'report_level': 'quiet'}
return publish_parts(content,
writer=Writer(),
settings_overrides=settings).get('html_body')
def rst2html(rst, path, context, request):
lstrip_rst = rst.lstrip()
if lstrip_rst and lstrip_rst[0] == '<':
return rst
settings = {
'halt_level': 6,
'input_encoding': 'UTF-8',
'output_encoding': 'UTF-8',
'initial_header_level': 2,
'file_insertion_enabled': 1,
'raw_enabled': 1,
'writer_name': 'html',
'language_code': 'zh_cn',
'context': context,
'request': request
}
# 表格生成的时候，会出现一个border=1，需要去除
rst = rst.replace('border="1"', '')
html_content = docutils.core.publish_parts(
rst,
source_path=path,
writer=Writer(),
settings_overrides=settings,
)['html_body']
return html_content
def rst2html(rst):
from docutils.core import publish_string
from docutils.writers.html4css1 import Writer, HTMLTranslator
class xia2HTMLTranslator(HTMLTranslator):
def __init__(self, document):
HTMLTranslator.__init__(self, document)
def visit_table(self, node):
self.context.append(self.compact_p)
self.compact_p = True
classes = ' '.join(['docutils', self.settings.table_style]).strip()
self.body.append(
self.starttag(node, 'table', CLASS=classes, border="0"))
def write_colspecs(self):
self.colspecs = []
xia2_root_dir = libtbx.env.find_in_repositories("xia2", optional=False)
args = {
'stylesheet_path': os.path.join(xia2_root_dir, 'css', 'voidspace.css')
}
w = Writer()
w.translator_class = xia2HTMLTranslator
return publish_string(rst,
writer=w,
settings=None,
settings_overrides=args)
def description_from_readme_rst(
rst_text: str) -> Tuple[Optional[str], Iterable[UpstreamDatum]]:
"""Description from README.rst."""
if platform.python_implementation() == "PyPy":
logger.debug(
'docutils does not appear to work on PyPy, skipping README.rst.')
return None, {}
try:
from docutils.core import publish_parts
except ModuleNotFoundError:
logger.debug('docutils not available, not parsing README.rst')
return None, {}
from docutils.writers.html4css1 import Writer
settings = {'initial_header_level': 2, 'report_level': 0}
html_text = publish_parts(rst_text,
writer=Writer(),
settings_overrides=settings).get('html_body')
try:
from bs4 import BeautifulSoup, FeatureNotFound
except ModuleNotFoundError:
logger.debug('BeautifulSoup not available, not parsing README.rst')
return None, {}
try:
soup = BeautifulSoup(html_text, 'lxml')
except FeatureNotFound:
logger.debug('lxml not available, not parsing README.rst')
return None, {}
return _description_from_basic_soup(list(soup.body.children)[0])
def parse_rst_parts(rst_input,
system_message_re=SYSTEM_MESSAGE_RE,
logger=logger):
if not isinstance(rst_input, str):
rst_input = '\n'.join(rst_input)
rst_error = None
parsing_error = None
settings_overrides = {
'initial_header_level': '2',
'traceback': True,
'warning_stream': StringIO(),
'embed_stylesheet': False,
'dump_settings': False,
'halt_level': 3,
}
try:
return publish_parts(
settings_overrides=settings_overrides,
writer=Writer(),
source=rst_input,
)
except SystemMessage as e:
rst_error = e
# parse docutils.utils.SystemMessage and re-raise SystemMessage
# on parsing error
try:
result = system_message_re.search(rst_error.args[0])
result = result.groupdict()
result['level'] = int(result['level'])
result['line'] = int(result['line'])
if result['short_description'][-1] == '.':
result['short_description'] = result['short_description'][:-1]
if 'long_description' not in result:
result['long_description'] = ''
except Exception as e:
parsing_error = e
logger.error('%s raised while analyzing %s',
parsing_error,
rst_error,
exc_info=True)
if parsing_error:
raise rst_error
raise reStructuredTextError(result['short_description'], **{
'system_message': rst_error,
**result,
})
def render_page(pagename):
"""Render page with docutils"""
path = os.path.abspath(os.path.join(DOC_DIR, pagename))
print "rendering: %s" % path
raw = open(path, 'r').read()
html_writer = Writer()
html = publish_string(raw, writer=html_writer)
return render_template('page.jinja', pagename=pagename, html=html)
def __init__(self):
self.writer = Writer()
self.writer.translator_class = GitHubHTMLTranslator
roles.register_canonical_role('kbd', kbd)
# Render source code in Sphinx doctest blocks
directives.register_directive('doctest', DoctestDirective)
def write():
"""A simple command to get the notebook document. Now defaults to HTML."""
import docutils, docutils.io
from docutils.writers.html4css1 import Writer
out = docutils.io.FileOutput()
out.encoding = 'unicode'
w = Writer()
w.write(document, out)
def render_rest(content, base_url):
# start by h2 and ignore invalid directives and so on
# (most likely from Sphinx)
#
# base_url is accepted for compatibility with other render_*
# functions but not used
#pylint: disable=unused-argument
settings = {'initial_header_level': 2, 'report_level': 0}
return publish_parts(content,
writer=Writer(),
settings_overrides=settings).get('html_body')
def visit_perform(self, node):
# Ideally, we should use sphinx but this is a simple temporary solution
from docutils import core
from docutils.writers.html4css1 import Writer
w = Writer()
try:
res = core.publish_parts(node.rule_docstring, writer=w)['html_body']
self.body.append('<div class="">' + res + '</div>' )
node.children = []
except Exception as err:
print(err)
self.body.append('<div class=""> no docstring </div>' )
def rst2html(file_path):
string = read_all(file_path)
w = Writer()
(_, path, _) = imp.find_module('template', rstserv.__path__)
overrides = {
'stylesheet': os.path.join(path, 'default.css'),
'stylesheet_path': None,
'initial_header_level': 2
}
r = publish_parts(string, writer=w, settings_overrides=overrides)
result = r['whole']
return result.encode('utf-8')
def convert_string_fragment(string):
""" Converts a string of reST text into an html fragment (ie no <header>,
<body>, etc tags).
"""
html_fragment_writer = Writer()
html_fragment_writer.translator_class = HTMLFragmentTranslator
return core.publish_string(
_fix_indent(string),
writer=html_fragment_writer,
# Suppress output of warnings in html
settings_overrides={'report_level': '5'})
def form_example(self, ctx):
form = formal.Form()
form.addField('restString',
formal.String(required=True),
widgetFactory=formal.ReSTTextArea)
if docutilsAvailable:
w = Writer()
w.translator_class = CustomisedHTMLTranslator
form.addField(
'customRestString', formal.String(required=True),
formal.widgetFactory(formal.ReSTTextArea, restWriter=w))
form.addAction(self.submitted)
return form
def renderHtml(string):
class NoHeaderHTMLTranslator(HTMLTranslator):
def __init__(self, document):
HTMLTranslator.__init__(self, document)
self.head_prefix = ['', '', '', '', '']
self.body_prefix = []
self.body_suffix = []
self.stylesheet = []
w = Writer()
w.translator_class = NoHeaderHTMLTranslator
r = Reader()
return core.publish_string(string, writer=w, reader=r)
def rst2alea(text=""):
"""Convert docstring into HTML (assuming docstring is in reST format)
This function uses docutils. Ideally it should use Sphinx. Consequently
many directives are notunderstood and even rise many error messages.
In order to prevent such messages, the cleanup method remove them.
:param text: the docstring
:returns: text in HTML format
.. todo:: implement conversion with Sphinx to have all SPhinx's directives interpreted.
"""
# res = lightsphinx.aFunction(text)
# return res
def cleanup(text):
newtext = ''
for line in text.splitlines():
if line.find('System Message') >= 0 or line.find(
'Unknown directive') >= 0:
pass
else:
newtext += line + '\n'
return newtext
try:
from docutils import core
import docutils.core2
import docutils.parsers.rst
from openalea.misc.sphinx_configuration import extensions
#for ext in extensions:
# docutils.parsers.rst.directives.register_directive('TestDirective', ext)
from docutils.writers.html4css1 import Writer
w = Writer()
res = core.publish_parts(text, writer=w)['html_body']
return cleanup(res)
except:
res = ''
if text is not None:
res += text
for name in [
':Parameters:', ':Returns:', ':Keywords:', ':Author:',
':Authors:'
]:
res = res.replace(name, '<b>' + name.replace(':', '') + '</b>')
res = res.replace('\n', '<br />')
return cleanup(res)
def test_docutils(self):
# from https://gist.github.com/mastbaum/2655700
import docutils.core
from docutils.nodes import TextElement, Inline
from docutils.parsers.rst import Directive
from docutils.writers.html4css1 import Writer, HTMLTranslator
class foo(Inline, TextElement):
pass
class Foo(Directive):
required_arguments = 1
optional_arguments = 0
has_content = True
def run(self):
thenode = foo(text=self.arguments[0])
return [thenode]
class MyHTMLTranslator(HTMLTranslator):
def __init__(self, document):
HTMLTranslator.__init__(self, document)
def visit_foo(self, node):
self.body.append(
self.starttag(node, 'span', '', style='background:red'))
self.body.append("<!--foo-->")
def depart_foo(self, node):
self.body.append('<!--foo--></span>')
directives.register_directive('foo', Foo)
html_writer = Writer()
html_writer.translator_class = MyHTMLTranslator
rest_text = '''
this is a test
==============
it is only a test
.. foo:: whee
'''.replace(" ", "")
bhtml = docutils.core.publish_string(source=rest_text,
writer=html_writer)
typstr = str # unicode#
html = typstr(bhtml, encoding="utf8")
if "<!--foo-->" not in html:
raise Exception(html)
def render(raw):
# Use a io.StringIO as the warning stream to prevent warnings from being
# printed to sys.stderr.
settings = SETTINGS.copy()
settings["warning_stream"] = io.StringIO()
writer = Writer()
writer.translator_class = ReadMeHTMLTranslator
try:
parts = publish_parts(raw, writer=writer, settings_overrides=settings)
except SystemMessage:
rendered = None
else:
rendered = parts.get("fragment")
return clean(rendered or raw), bool(rendered)
def render(self, settings_overrides={}):
# default settings for the renderer
overrides = {
'halt_level': 6,
'input_encoding': 'unicode',
'output_encoding': 'unicode',
'initial_header_level': 3,
}
overrides.update(settings_overrides)
writer = Writer()
writer.translator_class = HTMLTranslator
html = docutils.core.publish_file(
source_path=self.context,
writer=writer,
settings_overrides=overrides,
)
return html
