def render_rst(directory, name, meta_parser, template):
# check if that file actually exists
path = safe_join(directory, name + '.rst')
if not os.path.exists(path):
abort(404)
# read file
with codecs.open(path, encoding='utf-8') as fd:
content = fd.read()
if not template:
# Strip out RST
content = content.replace('.. meta::\n', '')
content = content.replace('.. contents::\n\n', '')
content = content.replace('.. raw:: html\n\n', '')
content = content.replace('\n.. [', '\n[')
content = content.replace(']_.', '].')
content = content.replace(']_,', '],')
content = content.replace(']_', '] ')
# Change highlight formatter
content = content.replace('{% highlight', "{% highlight formatter='textspec'")
# Metatags
for (metatag, label) in METATAG_LABELS.items():
content = content.replace(' :%s' % metatag, label)
# render the post with Jinja2 to handle URLs etc.
rendered_content = render_template_string(content)
rendered_content = rendered_content.replace('</pre></div>', ' </pre></div>')
if not template:
# Send response
r = make_response(rendered_content)
r.mimetype = 'text/plain'
return r
# Render the ToC
doctree = publish_doctree(source=rendered_content)
bullet_list = doctree[1][1]
doctree.clear()
doctree.append(bullet_list)
reader = Reader(parser_name='null')
pub = Publisher(reader, None, None,
source=io.DocTreeInput(doctree),
destination_class=io.StringOutput)
pub.set_writer('html')
pub.publish()
toc = pub.writer.parts['fragment']
# Remove the ToC from the main document
rendered_content = rendered_content.replace('.. contents::\n', '')
# publish the spec with docutils
parts = publish_parts(source=rendered_content, source_path=directory, writer_name="html")
meta = meta_parser(parts['meta'])
if (directory == PROPOSAL_DIR):
meta['num'] = int(name[:3])
return render_template(template, title=parts['title'], toc=toc, body=parts['fragment'], name=name, meta=meta)
def process_description(source, output_encoding='unicode'):
"""Given an source string, returns an HTML fragment as a string.
The return value is the contents of the <body> tag.
Parameters:
- `source`: A multi-line text string; required.
- `output_encoding`: The desired encoding of the output. If a Unicode
string is desired, use the default value of "unicode" .
"""
# Dedent all lines of `source`.
source = trim_docstring(source)
settings_overrides = {
'raw_enabled': 0, # no raw HTML code
'file_insertion_enabled': 0, # no file/URL access
'halt_level': 2, # at warnings or errors, raise an exception
'report_level': 5, # never report problems with the reST code
}
parts = None
# Convert reStructuredText to HTML using Docutils.
document = publish_doctree(source=source,
settings_overrides=settings_overrides)
for node in document.traverse():
if node.tagname == '#text':
continue
if node.hasattr('refuri'):
uri = node['refuri']
elif node.hasattr('uri'):
uri = node['uri']
else:
continue
o = urlparse(uri)
if o.scheme not in ALLOWED_SCHEMES:
raise TransformError('link scheme not allowed: {0}'.format(uri))
# now turn the transformed document into HTML
reader = readers.doctree.Reader(parser_name='null')
pub = Publisher(reader,
source=io.DocTreeInput(document),
destination_class=io.StringOutput)
pub.set_writer('html')
pub.process_programmatic_settings(None, settings_overrides, None)
pub.set_destination(None, None)
pub.publish()
parts = pub.writer.parts
output = parts['body']
if output_encoding != 'unicode':
output = output.encode(output_encoding)
return output
def parts_from_doctree(document):
reader = doctree.Reader(parser_name='null')
pub = docutils_core.Publisher(reader,
None,
None,
source=io.DocTreeInput(document),
destination_class=io.StringOutput)
pub.set_writer("html4css1")
pub.process_programmatic_settings(None, None, None)
pub.set_destination(None, None)
pub.publish(enable_exit_status=False)
return pub.writer.parts
def render_readme_like_pypi(source, output_encoding='unicode'):
"""
Render a ReST document just like PyPI does.
"""
# Dedent all lines of `source`.
source = trim_docstring(source)
settings_overrides = {
'raw_enabled': 0, # no raw HTML code
'file_insertion_enabled': 0, # no file/URL access
'halt_level': 2, # at warnings or errors, raise an exception
'report_level': 5, # never report problems with the reST code
}
parts = None
# Convert reStructuredText to HTML using Docutils.
document = publish_doctree(source=source,
settings_overrides=settings_overrides)
for node in document.traverse():
if node.tagname == '#text':
continue
if node.hasattr('refuri'):
uri = node['refuri']
elif node.hasattr('uri'):
uri = node['uri']
else:
continue
o = urlparse(uri)
if o.scheme not in ALLOWED_SCHEMES:
raise TransformError('link scheme not allowed: {0}'.format(uri))
# now turn the transformed document into HTML
reader = readers.doctree.Reader(parser_name='null')
pub = Publisher(reader,
source=io.DocTreeInput(document),
destination_class=io.StringOutput)
pub.set_writer('html')
pub.process_programmatic_settings(None, settings_overrides, None)
pub.set_destination(None, None)
pub.publish()
parts = pub.writer.parts
output = parts['body']
if output_encoding != 'unicode':
output = output.encode(output_encoding)
return output
def publish_from_doctree(
document,
destination_path=None,
writer=None,
writer_name="pseudoxml",
settings=None,
settings_spec=None,
settings_overrides=None,
config_section=None,
enable_exit_status=False,
):
"""
Set up & run a `Publisher` to render from an existing document
tree data structure, for programmatic use with string I/O. Return
the encoded string output.
Note that document.settings is overridden; if you want to use the settings
of the original `document`, pass settings=document.settings.
Also, new document.transformer and document.reporter objects are
generated.
For encoded string output, be sure to set the 'output_encoding' setting to
the desired encoding. Set it to 'unicode' for unencoded Unicode string
output. Here's one way::
publish_from_doctree(
..., settings_overrides={'output_encoding': 'unicode'})
Parameters: `document` is a `docutils.nodes.document` object, an existing
document tree.
Other parameters: see `publish_programmatically`.
"""
reader = docutils.readers.doctree.Reader(parser_name="null")
pub = Publisher(
reader,
None,
writer,
source=io.DocTreeInput(document),
destination_class=io.StringOutput,
settings=settings,
)
if not writer and writer_name:
pub.set_writer(writer_name)
pub.process_programmatic_settings(settings_spec, settings_overrides,
config_section)
pub.set_destination(None, destination_path)
return pub.publish(enable_exit_status=enable_exit_status)
def pypi_rest2html(source, output_encoding="unicode"):
"""
>>> pypi_rest2html("test!")
u'<p>test!</p>\n'
"""
settings_overrides = {
"raw_enabled": 0, # no raw HTML code
"file_insertion_enabled": 0, # no file/URL access
"halt_level": 2, # at warnings or errors, raise an exception
"report_level": 5, # never report problems with the reST code
}
# Convert reStructuredText to HTML using Docutils.
document = publish_doctree(source=source,
settings_overrides=settings_overrides)
for node in document.traverse():
if node.tagname == "#text":
continue
if node.hasattr("refuri"):
uri = node["refuri"]
elif node.hasattr("uri"):
uri = node["uri"]
else:
continue
o = urlparse(uri)
if o.scheme not in ALLOWED_SCHEMES:
raise TransformError("link scheme not allowed")
# now turn the transformed document into HTML
reader = readers.doctree.Reader(parser_name="null")
pub = Publisher(reader,
source=io.DocTreeInput(document),
destination_class=io.StringOutput)
pub.set_writer("html")
pub.process_programmatic_settings(None, settings_overrides, None)
pub.set_destination(None, None)
pub.publish()
parts = pub.writer.parts
output = parts["body"]
if output_encoding != "unicode":
output = output.encode(output_encoding)
return output
def write_doc(self, docname, doctree):
outfilename = path.join(self.outdir, self.file_transform(docname))
logger.debug(outfilename)
reader = docutils.readers.doctree.Reader(parser_name='null')
#Note, want to use our OdtWriter class here - but it doesn't work yet
writer = Writer()
pub = Publisher(reader,
None,
writer,
settings=None,
source=io.DocTreeInput(doctree),
destination_class=io.BinaryFileOutput)
settings_spec = None
settings_overrides = {'output_encoding': 'unicode'}
config_section = None
pub.process_programmatic_settings(settings_spec, settings_overrides,
config_section)
destination = None
destination_path = outfilename
pub.set_destination(destination, destination_path)
output = pub.publish(enable_exit_status=False)
def create_toc(doctree, depth=9223372036854775807, writer_name='html',
exclude_first_section=True, href_prefix=None, id_prefix='toc-ref-'):
"""
Create a Table of Contents (TOC) from the given doctree
Returns: (docutils.core.Publisher instance, output string)
`writer_name`: represents a reST writer name and determines the type of
output returned.
Example:
pub = blazeutils.rst.rst2pub(toc_rst)
pub, html_output = blazeutils.rst.create_toc(pub.document)
# a full HTML document (probably not what you want most of the time)
print html_output
# just the TOC
print pub.writer.parts['body']
"""
# copy the doctree since Content alters some settings on the original
# document
doctree = doctree.deepcopy()
# we want to be able to customize ids to avoid clashes if needed
doctree.settings.auto_id_prefix = id_prefix
details = {
'depth': depth,
}
# Assuming the document has one primary heading and then sub-sections, we
# want to be able to give just the sub-sections
startnode = None
if exclude_first_section:
nodes = doctree.traverse(docutils.nodes.section)
if nodes:
startnode = nodes[0]
# use the Contents transform to build the TOC node structure from the
# document
c = Contents(doctree)
# this startnode isn't really used as the start node, its only used for
# to pull settings from
c.startnode = BlankObject(details=details)
# since this toc is detached from the rest of the document, we don't want
# backlinks
c.backlinks = 'none'
# build the nodes
toc_nodes = c.build_contents(startnode or doctree)
# create a new document with the new nodes
toc_doc = new_document(None)
toc_doc += toc_nodes
# fix fragements that reference the same page
if href_prefix:
prefix_refids(toc_doc, href_prefix)
# setup a publisher and publish from the TOC document
reader = docutils.readers.doctree.Reader(parser_name='null')
pub = Publisher(
reader, None, None,
source=io.DocTreeInput(toc_doc),
destination_class=io.StringOutput
)
pub.set_writer(writer_name)
final_settings_overrides = default_rst_opts.copy()
pub.process_programmatic_settings(
None, final_settings_overrides, None)
output = pub.publish()
return pub, output
