Add -A option to pass values into HTML templates.

sphinx/__init__.py

@@ -39,6 +39,7 @@ Options: -b <builder> -- builder to use; default is html
          -c <path> -- path where configuration file (conf.py) is located
                       (default: same as sourcedir)
          -D <setting=value> -- override a setting in configuration
+         -A <name=value>    -- pass a value into the templates, for HTML builder
          -N        -- do not do colored output
          -q        -- no output on stdout, just warnings on stderr
          -P        -- run Pdb on exception
@@ -59,7 +60,7 @@ def main(argv=sys.argv):
         nocolor()
 
     try:
-        opts, args = getopt.getopt(argv[1:], 'ab:d:c:D:NEqP')
+        opts, args = getopt.getopt(argv[1:], 'ab:d:c:D:A:NEqP')
         srcdir = confdir = path.abspath(args[0])
         if not path.isdir(srcdir):
             print >>sys.stderr, 'Error: Cannot find source directory.'
@@ -89,6 +90,7 @@ def main(argv=sys.argv):
     freshenv = use_pdb = False
     status = sys.stdout
     confoverrides = {}
+    htmlcontext = {}
     doctreedir = path.join(outdir, '.doctrees')
     for opt, val in opts:
         if opt == '-b':
@@ -107,12 +109,29 @@ def main(argv=sys.argv):
                       'Error: Configuration directory doesn\'t contain conf.py file.'
                 return 1
         elif opt == '-D':
-            key, val = val.split('=')
+            try:
+                key, val = val.split('=')
+            except ValueError:
+                print >>sys.stderr, \
+                      'Error: -D option argument must be in the form name=value.'
+                return 1
             try:
                 val = int(val)
             except ValueError:
                 pass
             confoverrides[key] = val
+        elif opt == '-A':
+            try:
+                key, val = val.split('=')
+            except ValueError:
+                print >>sys.stderr, \
+                      'Error: -A option argument must be in the form name=value.'
+                return 1
+            try:
+                val = int(val)
+            except ValueError:
+                pass
+            htmlcontext[key] = val
         elif opt == '-N':
             nocolor()
         elif opt == '-E':
@@ -121,6 +140,7 @@ def main(argv=sys.argv):
             status = StringIO()
         elif opt == '-P':
             use_pdb = True
+    confoverrides['html_context'] = htmlcontext
 
     try:
         app = Sphinx(srcdir, confdir, outdir, doctreedir, buildername,

sphinx/builder.py

@@ -449,6 +449,7 @@ class StandaloneHTMLBuilder(Builder):
             logo = logo,
             favicon = favicon,
         )
+        self.globalcontext.update(self.config.html_context)
 
     def get_doc_context(self, docname, body, metatags):
         """Collect items for the template context of a page."""

sphinx/config.py

@@ -71,6 +71,7 @@ class Config(object):
         html_use_opensearch = ('', False),
         html_file_suffix = (None, False),
         html_show_sphinx = (True, False),
+        html_context = ({}, False),
 
         # HTML help only options
         htmlhelp_basename = ('pydoc', False),

tests/root/_templates/layout.html

@@ -0,0 +1,4 @@
+{% extends "!layout.html" %}
+{% block extrahead %}
+<meta name="hc" content="{{ hckey }}" />
+{% endblock %}

tests/root/conf.py

@@ -133,6 +133,8 @@ html_last_updated_fmt = '%b %d, %Y'
 # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
 #html_file_suffix = ''
 
+html_context = {'hckey': 'hcval'}
+
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'SphinxTestsdoc'
 

tests/test_build.py

@@ -67,6 +67,7 @@ HTML_XPATH = {
         ".//a[@href='#mod.Cls']": '',
     },
     'contents.html': {
+        ".//meta[@name='hc'][@content='hcval']": '',
         ".//td[@class='label']": '[Ref1]',
     },
 }