Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
executable file 286 lines (236 sloc) 9.78 KB
#!/usr/bin/env python
rest2html - A small wrapper file for parsing ReST files at GitHub.
Written in 2008 by Jannis Leidel <>
Brandon Keepers <>
Bryan Veloso <>
Chris Wanstrath <>
Dave Abrahams <>
Garen Torikian <>
Gasper Zejn <>
Michael Jones <>
Sam Whited <>
Tyler Chung <>
Vicent Marti <>
To the extent possible under law, the author(s) have dedicated all copyright
and related and neighboring rights to this software to the public domain
worldwide. This software is distributed without any warranty.
You should have received a copy of the CC0 Public Domain Dedication along with
this software. If not, see <>.
__author__ = "Jannis Leidel"
__license__ = "CC0"
__version__ = "0.1"
import sys
import os
# This fixes docutils failing with unicode parameters to CSV-Table. The -S
# switch and the following 3 lines can be removed after upgrading to python 3.
if sys.version_info[0] < 3:
import site
import locale
locale.setlocale(locale.LC_ALL, '')
import codecs
import io
from docutils import nodes
from docutils.parsers.rst import directives, roles
from docutils.parsers.rst.directives.body import CodeBlock, Directive
from docutils.core import publish_parts
from docutils.writers.html4css1 import Writer, HTMLTranslator
from docutils.parsers.rst.states import Body
from docutils import nodes
# By default, docutils provides two choices for unknown directives:
# - Show errors if the reporting level is high enough
# - Silently do not display them otherwise
# Comments are not displayed, either.
# This code monkey-patches docutils to show preformatted lines
# in both these cases.
# Recommended practice for repositories with rst files:
# - If github is the preferred viewer for the rst files (e.g. README.rst),
# then design the files to properly display for github. E.g., do not
# include unknown directives or restructuredText comments.
# - If github is NOT the preferred viewer for the rst files (e.g.
# the files are designed to be used with sphinx extensions at readthedocs)
# then include a restructuredText comment at the top of the file
# explaining that the document will display much more nicely with its
# preferred viewer, e.g. at readthedocs.
original_behavior = False # Documents original docutils behavior
github_display = True
def unknown_directive(self, type_name):
lineno = self.state_machine.abs_line_number()
indented, indent, offset, blank_finish = \
self.state_machine.get_first_known_indented(0, strip_indent=False)
text = '\n'.join(indented)
if original_behavior:
error = self.reporter.error(
'Unknown directive type "%s".' % type_name,
nodes.literal_block(text, text), line=lineno)
return [error], blank_finish
elif github_display:
cls = ['unknown_directive']
result = [nodes.literal_block(text, text, classes=cls)]
return result, blank_finish
return [nodes.comment(text, text)], blank_finish
def comment(self, match):
if not match.string[match.end():].strip() \
and self.state_machine.is_next_line_blank(): # an empty comment?
return [nodes.comment()], 1 # "A tiny but practical wart."
indented, indent, offset, blank_finish = \
while indented and not indented[-1].strip():
if not original_behavior:
firstline = ''.join(indented[:1]).split()
if ' '.join(firstline[:2]) == 'github display':
if len(firstline) == 3 and firstline[2] in ('on', 'off'):
global github_display
github_display = firstline[2] == 'on'
if len(indented) == 1:
return [nodes.comment()], 1
text = '\n'.join(indented[1:])
cls = ['github_comment']
result = [nodes.literal_block(text, text, classes=cls)]
return result, blank_finish
text = '\n'.join(indented)
return [nodes.comment(text, text)], blank_finish
Body.comment = comment
Body.unknown_directive = unknown_directive
'cloak_email_addresses': False,
'file_insertion_enabled': False,
'raw_enabled': True,
'strip_comments': True,
'doctitle_xform': True,
'initial_header_level': 2,
'report_level': 5,
'syntax_highlight': 'none',
'math_output': 'latex',
'field_name_limit': 50,
default_highlight_language = None
class HighlightDirective(Directive):
required_arguments = 1
optional_arguments = 1
option_spec = {}
def run(self):
"""Track the default syntax highlighting language
global default_highlight_language
default_highlight_language = self.arguments[0]
return []
class DoctestDirective(CodeBlock):
"""Render Sphinx 'doctest:: [group]' blocks as 'code:: python'
def run(self):
"""Discard any doctest group argument, render contents as python code
self.arguments = ['python']
return super(DoctestDirective, self).run()
class GitHubHTMLTranslator(HTMLTranslator):
# removes the <div class="document"> tag wrapped around docs
# see also: (warning! sourceforge link.)
def depart_document(self, node):
HTMLTranslator.depart_document(self, node)
self.html_body.pop(0) # pop the starting <div> off
self.html_body.pop() # pop the ending </div> off
# technique for visiting sections, without generating additional divs
# see also:
# the a is to support ::contents with ::sectnums:
def visit_section(self, node):
id_attribute = node.attributes['ids'][0]
self.body.append('<a name="%s"></a>\n' % id_attribute)
self.section_level += 1
def depart_section(self, node):
self.section_level -= 1
def visit_literal_block(self, node):
classes = node.attributes['classes']
if len(classes) >= 2 and classes[0] == 'code':
language = classes[1]
del classes[:]
self.body.append(self.starttag(node, 'pre', lang=language))
elif default_highlight_language is not None:
self.body.append(self.starttag(node, 'pre', lang=default_highlight_language))
self.body.append(self.starttag(node, 'pre'))
def visit_doctest_block(self, node):
self.body.append(self.starttag(node, 'pre', lang='pycon'))
# always wrap two-backtick rst inline literals in <code>, not <tt>
# this also avoids the generation of superfluous <span> tags
def visit_literal(self, node):
self.body.append(self.starttag(node, 'code', suffix=''))
def depart_literal(self, node):
def visit_table(self, node):
classes = ' '.join(['docutils', self.settings.table_style]).strip()
self.starttag(node, 'table', CLASS=classes))
def depart_table(self, node):
def depart_image(self, node):
uri = node['uri']
ext = os.path.splitext(uri)[1].lower()
# we need to swap RST's use of `object` with `img` tags
# see
if ext == ".svg":
# preserve essential attributes
atts = {}
for attribute, value in node.attributes.items():
# we have no time for empty values
if value:
if attribute == "uri":
atts['src'] = value
atts[attribute] = value
# toss off `object` tag
# add on `img` with attributes
self.body.append(self.starttag(node, 'img', **atts))
HTMLTranslator.depart_image(self, node)
def kbd(name, rawtext, text, lineno, inliner, options={}, content=[]):
return [nodes.raw('', '<kbd>%s</kbd>' % text, format='html')], []
def main():
Parses the given ReST file or the redirected string input and returns the
HTML body.
Usage: rest2html < README.rst
rest2html README.rst
text =[1], 'r', 'utf-8').read()
except IOError: # given filename could not be found
return ''
except IndexError: # no filename given
if sys.version_info[0] < 3: # python 2.x
text =
else: # python 3
input_stream = io.TextIOWrapper(sys.stdin.buffer, encoding='utf-8')
text =
writer = Writer()
writer.translator_class = GitHubHTMLTranslator
roles.register_canonical_role('kbd', kbd)
# Render source code in Sphinx doctest blocks
directives.register_directive('doctest', DoctestDirective)
# Set default highlight language
directives.register_directive('highlight', HighlightDirective)
parts = publish_parts(text, writer=writer, settings_overrides=SETTINGS)
if 'html_body' in parts:
html = parts['html_body']
# publish_parts() in python 2.x return dict values as Unicode type
# in py3k Unicode is unavailable and values are of str type
if isinstance(html, str):
return html
return html.encode('utf-8')
return ''
if __name__ == '__main__':
if sys.version_info[0] < 3: # python 2.x
sys.stdout.write("%s%s" % (main(), "\n"))
else: # python 3
output_stream = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
output_stream.write("%s%s" % (main(), "\n"))
You can’t perform that action at this time.