From fa7c1de04ad5c65ed3c81976c153b8e32ff5f011 Mon Sep 17 00:00:00 2001 From: milde Date: Tue, 10 Mar 2015 14:15:17 +0000 Subject: [PATCH] New basic HTML writer: generates polyglott HTML 5 / XHTML 1.1 (transitional) git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@7815 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docutils/writers/html_base/__init__.py | 1721 ++++++++++++++++++++ docutils/writers/{html4css1 => html_base}/math.css | 0 docutils/writers/html_base/template.txt | 8 + tools/rst2html5.py | 35 + 4 files changed, 1764 insertions(+) create mode 100644 docutils/writers/html_base/__init__.py rename docutils/writers/{html4css1 => html_base}/math.css (100%) create mode 100644 docutils/writers/html_base/template.txt create mode 100755 tools/rst2html5.py diff --git a/docutils/writers/html_base/__init__.py b/docutils/writers/html_base/__init__.py new file mode 100644 index 000000000..19f33312c --- /dev/null +++ b/docutils/writers/html_base/__init__.py @@ -0,0 +1,1721 @@ +# .. coding: utf8 +# :Author: Günter Milde +# :Revision: $Revision$ +# :Date: $Date: 2005-06-28$ +# :Copyright: © 2005, 2009 Günter Milde. +# :License: Released under the terms of the `2-Clause BSD license`_, in short: +# +# Copying and distribution of this file, with or without modification, +# are permitted in any medium without royalty provided the copyright +# notice and this notice are preserved. +# This file is offered as-is, without any warranty. +# +# .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause + +# Use "best practice" as recommended by the W3C: +# http://www.w3.org/2009/cheatsheet/ + + +""" +Basic HyperText Markup Language document tree Writer. + +The output conforms to the `HTML 5` specification as well as +to `XHTML 1.0 transitional`. + +The cascading style sheet "html-base.css" is required for proper viewing. +""" +__docformat__ = 'reStructuredText' + +import sys +import os +import os.path +import re +import urllib +try: # check for the Python Imaging Library + import PIL.Image +except ImportError: + try: # sometimes PIL modules are put in PYTHONPATH's root + import Image + class PIL(object): pass # dummy wrapper + PIL.Image = Image + except ImportError: + PIL = None +import docutils +from docutils import frontend, nodes, utils, writers, languages, io +from docutils.utils.error_reporting import SafeString +from docutils.transforms import writer_aux +from docutils.utils.math import unichar2tex, pick_math_environment, math2html +from docutils.utils.math.latex2mathml import parse_latex_math + +class Writer(writers.Writer): + + supported = ('html', 'html5', 'xhtml') + """Formats this writer supports.""" + + default_stylesheets = ['html-base.css'] + default_stylesheet_dirs = ['.', os.path.abspath(os.path.dirname(__file__))] + + default_template = 'template.txt' + default_template_path = os.path.join( + os.path.dirname(os.path.abspath(__file__)), default_template) + + settings_spec = ( + 'HTML-Specific Options', + None, + (('Specify the template file (UTF-8 encoded). Default is "%s".' + % default_template_path, + ['--template'], + {'default': default_template_path, 'metavar': ''}), + ('Comma separated list of stylesheet URLs. ' + 'Overrides previous --stylesheet and --stylesheet-path settings.', + ['--stylesheet'], + {'metavar': '', 'overrides': 'stylesheet_path', + 'validator': frontend.validate_comma_separated_list}), + ('Comma separated list of stylesheet paths. ' + 'Relative paths are expanded if a matching file is found in ' + 'the --stylesheet-dirs. With --link-stylesheet, ' + 'the path is rewritten relative to the output HTML file. ' + 'Default: "%s"' % ','.join(default_stylesheets), + ['--stylesheet-path'], + {'metavar': '', 'overrides': 'stylesheet', + 'validator': frontend.validate_comma_separated_list, + 'default': default_stylesheets}), + ('Embed the stylesheet(s) in the output HTML file. The stylesheet ' + 'files must be accessible during processing. This is the default.', + ['--embed-stylesheet'], + {'default': 1, 'action': 'store_true', + 'validator': frontend.validate_boolean}), + ('Link to the stylesheet(s) in the output HTML file. ' + 'Default: embed stylesheets.', + ['--link-stylesheet'], + {'dest': 'embed_stylesheet', 'action': 'store_false'}), + ('Comma-separated list of directories where stylesheets are found. ' + 'Used by --stylesheet-path when expanding relative path arguments. ' + 'Default: "%s"' % default_stylesheet_dirs, + ['--stylesheet-dirs'], + {'metavar': '', + 'validator': frontend.validate_comma_separated_list, + 'default': default_stylesheet_dirs}), + ('Specify the initial header level. Default is 1 for "

%s ' + '(%s%s)%s
\n' + % (node['type'], node['level'], + self.encode(node['source']), line, backref_text)) + + def depart_system_message(self, node): + self.body.append('\n') + + # tables + # ------ + # no hard-coded border setting in the table head:: + + def visit_table(self, node): + classes = [cls.strip(u' \t\n') + for cls in self.settings.table_style.split(',')] + tag = self.starttag(node, 'table', CLASS=' '.join(classes)) + self.body.append(tag) + + def depart_table(self, node): + self.body.append('\n') + + def visit_target(self, node): + if not ('refuri' in node or 'refid' in node + or 'refname' in node): + self.body.append(self.starttag(node, 'span', '', CLASS='target')) + self.context.append('') + else: + self.context.append('') + + def depart_target(self, node): + self.body.append(self.context.pop()) + + # no hard-coded vertical alignment in table body:: + + def visit_tbody(self, node): + self.write_colspecs() + self.body.append(self.context.pop()) # '\n' or '' + self.body.append(self.starttag(node, 'tbody')) + + def depart_tbody(self, node): + self.body.append('\n') + + def visit_term(self, node): + self.body.append(self.starttag(node, 'dt', '')) + + def depart_term(self, node): + """ + Leave the end tag to `self.visit_definition()`, in case there's a + classifier. + """ + pass + + def visit_tgroup(self, node): + # Mozilla needs : + self.body.append(self.starttag(node, 'colgroup')) + # Appended by thead or tbody: + self.context.append('\n') + node.stubs = [] + + def depart_tgroup(self, node): + pass + + def visit_thead(self, node): + self.write_colspecs() + self.body.append(self.context.pop()) # '\n' + # There may or may not be a ; this is for to use: + self.context.append('') + self.body.append(self.starttag(node, 'thead')) + + def depart_thead(self, node): + self.body.append('\n') + + def visit_title(self, node): + """Only 6 section levels are supported by HTML.""" + check_id = 0 # TODO: is this a bool (False) or a counter? + close_tag = '
\n' + if isinstance(node.parent, nodes.topic): + self.body.append( + self.starttag(node, 'p', '', CLASS='topic-title first')) + elif isinstance(node.parent, nodes.sidebar): + self.body.append( + self.starttag(node, 'p', '', CLASS='sidebar-title')) + elif isinstance(node.parent, nodes.Admonition): + self.body.append( + self.starttag(node, 'p', '', CLASS='admonition-title')) + elif isinstance(node.parent, nodes.table): + self.body.append( + self.starttag(node, 'caption', '')) + close_tag = '\n' + elif isinstance(node.parent, nodes.document): + self.body.append(self.starttag(node, 'h1', '', CLASS='title')) + close_tag = '

\n' + self.in_document_title = len(self.body) + else: + assert isinstance(node.parent, nodes.section) + h_level = self.section_level + self.initial_header_level - 1 + atts = {} + if (len(node.parent) >= 2 and + isinstance(node.parent[1], nodes.subtitle)): + atts['CLASS'] = 'with-subtitle' + self.body.append( + self.starttag(node, 'h%s' % h_level, '', **atts)) + atts = {} + if node.hasattr('refid'): + atts['class'] = 'toc-backref' + atts['href'] = '#' + node['refid'] + if atts: + self.body.append(self.starttag({}, 'a', '', **atts)) + close_tag = '\n' % (h_level) + else: + close_tag = '\n' % (h_level) + self.context.append(close_tag) + + def depart_title(self, node): + self.body.append(self.context.pop()) + if self.in_document_title: + self.title = self.body[self.in_document_title:-1] + self.in_document_title = 0 + self.body_pre_docinfo.extend(self.body) + self.html_title.extend(self.body) + del self.body[:] + + def visit_title_reference(self, node): + self.body.append(self.starttag(node, 'cite', '')) + + def depart_title_reference(self, node): + self.body.append('') + + def visit_topic(self, node): + self.body.append(self.starttag(node, 'div', CLASS='topic')) + self.topic_classes = node['classes'] + # TODO: replace with :: + # self.in_contents = 'contents' in node['classes'] + + def depart_topic(self, node): + self.body.append('\n') + self.topic_classes = [] + # TODO self.in_contents = False + + def visit_transition(self, node): + self.body.append(self.emptytag(node, 'hr', CLASS='docutils')) + + def depart_transition(self, node): + pass + + def visit_version(self, node): + self.visit_docinfo_item(node, 'version', meta=False) + + def depart_version(self, node): + self.depart_docinfo_item() + + def unimplemented_visit(self, node): + raise NotImplementedError('visiting unimplemented node type: %s' + % node.__class__.__name__) + + +class SimpleListChecker(nodes.GenericNodeVisitor): + + """ + Raise `nodes.NodeFound` if non-simple list item is encountered. + + Here "simple" means a list item containing nothing other than a single + paragraph, a simple list, or a paragraph followed by a simple list. + + This version also checks for simple field lists and docinfo. + """ + + def default_visit(self, node): + raise nodes.NodeFound + + def visit_list_item(self, node): + # print "visiting list item", node.__class__ + children = [child for child in node.children + if not isinstance(child, nodes.Invisible)] + # print "has %s visible children" % len(children) + if (children and isinstance(children[0], nodes.paragraph) + and (isinstance(children[-1], nodes.bullet_list) or + isinstance(children[-1], nodes.enumerated_list) or + isinstance(children[-1], nodes.field_list))): + children.pop() + # print "%s children remain" % len(children) + if len(children) <= 1: + return + else: + # print "found", child.__class__, "in", node.__class__ + raise nodes.NodeFound + + def pass_node(self, node): + pass + + def ignore_node(self, node): + # ignore nodes that are never complex (can contain only inline nodes) + raise nodes.SkipNode + + # Paragraphs and text + visit_Text = ignore_node + visit_paragraph = ignore_node + + # Lists + visit_bullet_list = pass_node + visit_enumerated_list = pass_node + visit_docinfo = pass_node + + # Docinfo nodes: + visit_author = ignore_node + visit_authors = visit_list_item + visit_address = visit_list_item + visit_contact = pass_node + visit_copyright = ignore_node + visit_date = ignore_node + visit_organization = ignore_node + visit_status = ignore_node + visit_version = visit_list_item + + # Definition list: + visit_definition_list = pass_node + visit_definition_list_item = pass_node + visit_term = ignore_node + visit_classifier = pass_node + visit_definition = visit_list_item + + # Field list: + visit_field_list = pass_node + visit_field = pass_node + # the field body corresponds to a list item + visit_field_body = visit_list_item + visit_field_name = ignore_node + + # Invisible nodes should be ignored. + visit_comment = ignore_node + visit_substitution_definition = ignore_node + visit_target = ignore_node + visit_pending = ignore_node diff --git a/docutils/writers/html4css1/math.css b/docutils/writers/html_base/math.css similarity index 100% rename from docutils/writers/html4css1/math.css rename to docutils/writers/html_base/math.css diff --git a/docutils/writers/html_base/template.txt b/docutils/writers/html_base/template.txt new file mode 100644 index 000000000..2591bce35 --- /dev/null +++ b/docutils/writers/html_base/template.txt @@ -0,0 +1,8 @@ +%(head_prefix)s +%(head)s +%(stylesheet)s +%(body_prefix)s +%(body_pre_docinfo)s +%(docinfo)s +%(body)s +%(body_suffix)s diff --git a/tools/rst2html5.py b/tools/rst2html5.py new file mode 100755 index 000000000..aa328f848 --- /dev/null +++ b/tools/rst2html5.py @@ -0,0 +1,35 @@ +#!/usr/bin/env python +# -*- coding: utf8 -*- +# :Copyright: © 2005, 2009 Günter Milde. +# :License: Released under the terms of the `2-Clause BSD license`_, in short: +# +# Copying and distribution of this file, with or without modification, +# are permitted in any medium without royalty provided the copyright +# notice and this notice are preserved. +# This file is offered as-is, without any warranty. +# +# .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause +# +# Revision: $Revision$ +# Date: $Date$ + +""" +A minimal front end to the Docutils Publisher, producing basic HTML 5 + +The output also conforms to XHTML 1.0 transitional +(except for the doctype declaration). +""" + +try: + import locale # module missing in Jython + locale.setlocale(locale.LC_ALL, '') +except locale.Error: + pass + +from docutils.core import publish_cmdline, default_description + +description = ('Generates HTML 5 documents from standalone ' + 'reStructuredText sources ' + + default_description) + +publish_cmdline(writer_name='html-base', description=description) -- 2.11.4.GIT