# Copyright (c) 2013 The Chromium Authors. All rights reserved. # Use of this source code is governed by a BSD-style license that can be # found in the LICENSE file. # # This is a Sphinx extension. # from __future__ import print_function import codecs from collections import namedtuple, OrderedDict import os import string from docutils import nodes from docutils.parsers.rst import Directive, directives from sphinx.util.osutil import ensuredir from sphinx.builders.html import StandaloneHTMLBuilder from sphinx.writers.html import HTMLWriter from sphinx.writers.html import SmartyPantsHTMLTranslator as HTMLTranslator from sphinx.util.console import bold PEPPER_VERSION = "31" # TODO(eliben): it may be interesting to use an actual Sphinx template here at # some point. PAGE_TEMPLATE = string.Template(r''' ${devsite_prefix}
${nonprod_meta_head}
# tags for them.
# Emit a simple tag without enabling "protect_literal_text" mode,
# so Sphinx's visit_Text doesn't mess with the contents.
self.body.append(self.starttag(node, 'code', suffix=''))
def depart_literal(self, node):
self.no_smarty -= 1
self.body.append('
')
def visit_literal_block(self, node):
# Don't insert "smart" quotes here
self.no_smarty += 1
# We don't use Sphinx's buildin pygments integration for code highlighting,
# because the devsite requires special tags for that and handles the
# highlighting on its own.
attrs = {'class': 'prettyprint'} if node.get('prettyprint', 1) else {}
self.body.append(self.starttag(node, 'pre', **attrs))
def depart_literal_block(self, node):
self.no_smarty -= 1
self.body.append('\n
\n')
def visit_paragraph(self, node):
# Don't generate s within the table of contents
if not self.within_toc:
HTMLTranslator.visit_paragraph(self, node)
def depart_paragraph(self, node):
if not self.within_toc:
HTMLTranslator.depart_paragraph(self, node)
def visit_section(self, node):
# devsite needs instead of
self.section_level += 1
self.body.append(self.starttag(node, 'section'))
def depart_section(self, node):
self.section_level -= 1
self.body.append('')
def visit_image(self, node):
# Paths to images in .rst sources should be absolute. This visitor does the
# required transformation for the path to be correct in the final HTML.
if self.builder.devsite_production_mode:
node['uri'] = self.builder.get_production_url(node['uri'])
HTMLTranslator.visit_image(self, node)
def visit_reference(self, node):
# In "kill_internal_links" mode, we don't emit the actual links for internal
# nodes.
if self.builder.kill_internal_links and node.get('internal'):
pass
else:
HTMLTranslator.visit_reference(self, node)
def depart_reference(self, node):
if self.builder.kill_internal_links and node.get('internal'):
pass
else:
HTMLTranslator.depart_reference(self, node)
def visit_title(self, node):
# Why this?
#
# Sphinx insists on inserting a Page Title
into the page, but this
# is not how the devsite wants it. The devsite inserts the page title on
# its own, the the extra h1 is duplication.
#
# Killing the doctree title node in a custom transform doesn't work, because
# Sphinx explicitly looks for it when writing a document. So instead we rig
# the HTML produced.
#
# When a title node is visited, and this is the h1-to-be, we ignore it and
# also set a flag that tells visit_Text not to print the actual text of the
# header.
# The h1 node is in the section whose parent is the document itself. Other
# sections have this top-section as their parent.
if (node.parent and node.parent.parent and
isinstance(node.parent.parent, nodes.document)):
# Internal flag. Also, nothing is pushed to the context. Our depart_title
# doesn't pop anything when this flag is set.
self.within_ignored_h1 = True
else:
HTMLTranslator.visit_title(self, node)
def depart_title(self, node):
if not self.within_ignored_h1:
HTMLTranslator.depart_title(self, node)
self.within_ignored_h1 = False
def visit_Text(self, node):
if not self.within_ignored_h1:
HTMLTranslator.visit_Text(self, node)
def visit_topic(self, node):
if 'contents' in node['classes']:
# Detect a TOC: this requires special treatment for devsite.
self.within_toc = True
# Emit