Support <meta> tags via meta directive.

CHANGES

@@ -15,6 +15,9 @@ New features added
   - The JavaScript search now searches for objects before searching in
     the full text.
 
+  - HTML ``<meta>`` tags via the docutils ``meta`` directive are now
+    supported.
+
   - ``SerializingHTMLBuilder`` was added as new abstract builder that
     can be subclassed to serialize build HTML in a specific format.  The
     ``PickleHTMLBuilder`` is a concrete subclass of it that uses pickle

sphinx/addnodes.py

@@ -85,10 +85,13 @@ class start_of_file(nodes.Element): pass
 # tabular column specification, used for the LaTeX writer
 class tabular_col_spec(nodes.Element): pass
 
+# meta directive -- same as docutils' standard meta node, but pickleable
+class meta(nodes.Special, nodes.PreBibliographic, nodes.Element): pass
+
 # make them known to docutils. this is needed, because the HTML writer
 # will choke at some point if these are not added
 nodes._add_node_class_names("""index desc desc_content desc_signature desc_type
       desc_addname desc_name desc_parameterlist desc_parameter desc_optional
       centered versionmodified seealso productionlist production toctree
       pending_xref compact_paragraph highlightlang literal_emphasis
-      glossary acks module start_of_file tabular_col_spec""".split())
+      glossary acks module start_of_file tabular_col_spec meta""".split())

sphinx/builder.py

@@ -450,7 +450,7 @@ class StandaloneHTMLBuilder(Builder):
             favicon = favicon,
         )
 
-    def get_doc_context(self, docname, body):
+    def get_doc_context(self, docname, body, metatags):
         """Collect items for the template context of a page."""
         # find out relations
         prev = next = None
@@ -502,6 +502,7 @@ class StandaloneHTMLBuilder(Builder):
             title = title,
             meta = meta,
             body = body,
+            metatags = metatags,
             rellinks = rellinks,
             sourcename = sourcename,
             toc = self.render_partial(self.env.get_toc_for(docname))['fragment'],
@@ -518,8 +519,9 @@ class StandaloneHTMLBuilder(Builder):
         self.docwriter.write(doctree, destination)
         self.docwriter.assemble_parts()
         body = self.docwriter.parts['fragment']
+        metatags = self.docwriter.clean_meta
 
-        ctx = self.get_doc_context(docname, body)
+        ctx = self.get_doc_context(docname, body, metatags)
         self.index_page(docname, doctree, ctx.get('title', ''))
         self.handle_page(docname, ctx, event_arg=doctree)
 

sphinx/environment.py

@@ -30,12 +30,14 @@ except ImportError:
     md5 = md5.new
 
 from docutils import nodes
-from docutils.io import FileInput
-from docutils.core import publish_doctree
+from docutils.io import FileInput, NullOutput
+from docutils.core import Publisher
 from docutils.utils import Reporter
 from docutils.readers import standalone
 from docutils.parsers.rst import roles
 from docutils.parsers.rst.languages import en as english
+from docutils.parsers.rst.directives.html import MetaBody
+from docutils.writers import UnfilteredWriter
 from docutils.transforms import Transform
 from docutils.transforms.parts import ContentsFilter
 
@@ -142,9 +144,17 @@ class SphinxStandaloneReader(standalone.Reader):
     Add our own transforms.
     """
     transforms = [DefaultSubstitutions, MoveModuleTargets, HandleCodeBlocks]
+
     def get_transforms(self):
-        tf = standalone.Reader.get_transforms(self)
-        return tf + self.transforms
+        return standalone.Reader.get_transforms(self) + self.transforms
+
+
+class SphinxDummyWriter(UnfilteredWriter):
+    supported = ('html',)  # needed to keep "meta" nodes
+
+    def translate(self):
+        pass
+
 
 
 class SphinxContentsFilter(ContentsFilter):
@@ -486,6 +496,9 @@ class BuildEnvironment:
                 self.warn(docname, 'default role %s not found' %
                           self.config.default_role)
 
+        self.docname = docname
+        self.settings['input_encoding'] = self.config.source_encoding
+
         class SphinxSourceClass(FileInput):
             def read(self):
                 data = FileInput.read(self)
@@ -495,12 +508,18 @@ class BuildEnvironment:
                     data = arg[0]
                 return data
 
-        self.docname = docname
-        self.settings['input_encoding'] = self.config.source_encoding
+        # publish manually
+        pub = Publisher(reader=SphinxStandaloneReader(),
+                        writer=SphinxDummyWriter(),
+                        source_class=SphinxSourceClass,
+                        destination_class=NullOutput)
+        pub.set_components(None, 'restructuredtext', None)
+        pub.process_programmatic_settings(None, self.settings, None)
+        pub.set_source(None, src_path)
+        pub.set_destination(None, None)
         try:
-            doctree = publish_doctree(None, src_path, SphinxSourceClass,
-                                      settings_overrides=self.settings,
-                                      reader=SphinxStandaloneReader())
+            pub.publish()
+            doctree = pub.document
         except UnicodeError, err:
             from sphinx.application import SphinxError
             raise SphinxError(err.message)
@@ -525,6 +544,9 @@ class BuildEnvironment:
         doctree.settings.warning_stream = None
         doctree.settings.env = None
         doctree.settings.record_dependencies = None
+        for metanode in doctree.traverse(MetaBody.meta):
+            # docutils' meta nodes aren't picklable because the class is nested
+            metanode.__class__ = addnodes.meta
 
         # cleanup
         self.docname = None

sphinx/htmlwriter.py

@@ -37,6 +37,7 @@ class HTMLWriter(Writer):
                      'footer', 'html_prolog', 'html_head', 'html_title',
                      'html_subtitle', 'html_body', ):
             setattr(self, attr, getattr(visitor, attr, None))
+        self.clean_meta = ''.join(visitor.meta[2:])
 
 
 class HTMLTranslator(BaseTranslator):

sphinx/templates/layout.html

@@ -87,6 +87,7 @@
 <html xmlns="http://www.w3.org/1999/xhtml">
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    {{ metatags }}
     {%- if builder != 'htmlhelp' %}
       {%- set titlesuffix = " &mdash; " + docstitle %}
     {%- endif %}