Merge pull request #57 from professorplumb/html-entity-plugin

Allows user to enter HTML entities such as © inline in RST instead of using the substitution definition method.

html_entity/README.rst

@@ -0,0 +1,30 @@
+HTML Entities for reStructuredText
+##################################
+
+This plugin allows you to enter HTML entities such as ©, <, • inline in a RST document, as opposed
+to the tedious method of creating substitution definitions.
+
+Roles
+=====
+
+Adds one inline role:
+
+::
+
+    :html_entity:
+
+Usage
+=====
+
+::
+
+    :html_entity:`copy` 2013 :html_entity:`lt` Pelican :html_entity:`gt` Industries :html_entity:`149` All Rights Reserved
+
+produces:
+
+|copy| 2013 |lt| Pelican |gt| Industries |bullet| All Rights Reserved
+
+.. |copy|   unicode:: U+000A9 .. COPYRIGHT SIGN
+.. |lt|     unicode:: U+003C  .. LESS THAN
+.. |gt|     unicode:: U+003E  .. GREATER THAN
+.. |bullet| unicode:: U+2022  .. BULLET

html_entity/html_entity.py

@@ -0,0 +1,46 @@
+"""
+HTML Entities for reStructured Text
+===================================
+
+Allows user to use HTML entities (©, •, etc.) in RST documents.
+
+Usage:
+:html_entity:`copy`
+:html_entity:`149`
+:html_entity:`#149`
+"""
+from __future__ import unicode_literals
+from docutils import nodes, utils
+from docutils.parsers.rst import roles
+from pelican.readers import PelicanHTMLTranslator
+import six
+
+
+class html_entity(nodes.Inline, nodes.Node):
+    # Subclassing Node directly since TextElement automatically appends the escaped element
+    def __init__(self, rawsource, text):
+        self.rawsource = rawsource
+        self.text = text
+        self.children = []
+        self.attributes = {}
+
+    def astext(self):
+        return self.text
+
+
+def entity_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
+    text = utils.unescape(text)
+    entity_code = text
+    try:
+        entity_code = "#{}".format(six.u(int(entity_code)))
+    except ValueError:
+        pass
+    entity_code = "&{};".format(entity_code)
+    return [html_entity(text, entity_code)], []
+
+
+def register():
+    roles.register_local_role('html_entity', entity_role)
+
+PelicanHTMLTranslator.visit_html_entity = lambda self, node: self.body.append(node.astext())
+PelicanHTMLTranslator.depart_html_entity = lambda self, node: None