From 4b9119f9905e608e74335214d9e15514d0adf2f7 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 18 Oct 2008 09:29:49 +0000 Subject: [PATCH] Support tags via meta directive. --- CHANGES | 3 +++ sphinx/addnodes.py | 5 ++++- sphinx/builder.py | 6 ++++-- sphinx/environment.py | 40 ++++++++++++++++++++++++++++-------- sphinx/htmlwriter.py | 1 + sphinx/templates/layout.html | 1 + 6 files changed, 44 insertions(+), 12 deletions(-) diff --git a/CHANGES b/CHANGES index 80e29155a..6ac05a805 100644 --- a/CHANGES +++ b/CHANGES @@ -15,6 +15,9 @@ New features added - The JavaScript search now searches for objects before searching in the full text. + - HTML ```` 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 diff --git a/sphinx/addnodes.py b/sphinx/addnodes.py index fe21981e6..8b20f7ac0 100644 --- a/sphinx/addnodes.py +++ b/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()) diff --git a/sphinx/builder.py b/sphinx/builder.py index e464a546a..d466bd703 100644 --- a/sphinx/builder.py +++ b/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) diff --git a/sphinx/environment.py b/sphinx/environment.py index a10c03345..6d32ba4d7 100644 --- a/sphinx/environment.py +++ b/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 diff --git a/sphinx/htmlwriter.py b/sphinx/htmlwriter.py index 815c42779..2d13b112c 100644 --- a/sphinx/htmlwriter.py +++ b/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): diff --git a/sphinx/templates/layout.html b/sphinx/templates/layout.html index a5cb52883..45826f803 100644 --- a/sphinx/templates/layout.html +++ b/sphinx/templates/layout.html @@ -87,6 +87,7 @@ + {{ metatags }} {%- if builder != 'htmlhelp' %} {%- set titlesuffix = " — " + docstitle %} {%- endif %}