sphinx-quickstart supports user templates (ref: #2912)

4 files changed, 61 insertions, 3 deletions

diff --git a/CHANGES b/CHANGES
index 6ae0f8e2c..c59fce53f 100644
--- a/CHANGES
+++ b/CHANGES
@@ -18,6 +18,8 @@ Features added
   LaTeX style file ``geometry.sty`` to set page layout
 * #2843: Add :start-at: and :end-at: options to literalinclude directive
 * #2527: Add ``:reversed:`` option to toctree directive
+* Add ``-t`` and ``-d`` option to ``sphinx-quickstart`` to support templating
+  generated sphinx project.
 
 Bugs fixed
 ----------
diff --git a/doc/invocation.rst b/doc/invocation.rst
index 37c5938c1..a723b43f3 100644
--- a/doc/invocation.rst
+++ b/doc/invocation.rst
@@ -138,6 +138,32 @@ Makefile and Batchfile creation options
 .. versionadded:: 1.3
    Add various options for sphinx-quickstart invocation.
 
+Project templating
+------------------
+
+.. option:: -t, --templatedir=TEMPLATEDIR
+
+   Template directory for template files.  You can modify the templates of
+   sphinx project files generated by quickstart.  Following Jinja2 template
+   files are allowed:
+
+   * master_doc.rst_t
+   * conf.py_t
+   * Makefile_t
+   * Makefile.new_t
+   * make.bat_t
+   * make.bat.new_t
+
+   In detail, please refer the system template files Sphinx provides.
+   (sphinx/templates/quickstart)
+
+.. option:: -d NAME=VALUE
+
+   Define a template variable
+
+.. versionadded:: 1.5
+   Project templating options for sphinx-quickstart
+
 
 Invocation of sphinx-build
 ==========================
diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py
index f7e6ad38a..61abbb092 100644
--- a/sphinx/quickstart.py
+++ b/sphinx/quickstart.py
@@ -182,6 +182,19 @@ def convert_python_source(source, rex=re.compile(r"[uU]('.*?')")):
         return source
 
 
+class QuickstartRenderer(SphinxRenderer):
+    def __init__(self, templatedir):
+        self.templatedir = templatedir or ''
+        super(QuickstartRenderer, self).__init__()
+
+    def render(self, template_name, context):
+        user_template = path.join(self.templatedir, path.basename(template_name))
+        if self.templatedir and path.exists(user_template):
+            return self.render_from_file(user_template, context)
+        else:
+            return super(QuickstartRenderer, self).render(template_name, context)
+
+
 def ask_user(d):
     """Ask the user for quickstart values missing from *d*.
 
@@ -357,9 +370,9 @@ directly.''')
     print()
 
 
-def generate(d, overwrite=True, silent=False):
+def generate(d, overwrite=True, silent=False, templatedir=None):
     """Generate project based on values in *d*."""
-    template = SphinxRenderer()
+    template = QuickstartRenderer(templatedir=templatedir)
 
     texescape.init()
     indent = ' ' * 4
@@ -588,6 +601,12 @@ def main(argv=sys.argv):
                      default=True,
                      help='use make-mode for Makefile/make.bat')
 
+    group = parser.add_option_group('Project templating')
+    group.add_option('-t', '--templatedir', metavar='TEMPLATEDIR', dest='templatedir',
+                     help='template directory for template files')
+    group.add_option('-d', metavar='NAME=VALUE', action='append', dest='variables',
+                     help='define a template variable')
+
     # parse options
     try:
         opts, args = parser.parse_args(argv[1:])
@@ -640,7 +659,14 @@ def main(argv=sys.argv):
         if isinstance(value, binary_type):
             d[key] = term_decode(value)
 
-    generate(d)
+    for variable in d.get('variables', []):
+        try:
+            name, value = variable.split('=')
+            d[name] = value
+        except ValueError:
+            print('Invalid template variable: %s' % variable)
+
+    generate(d, templatedir=opts.templatedir)
 
 if __name__ == '__main__':
     sys.exit(main(sys.argv))
diff --git a/sphinx/util/template.py b/sphinx/util/template.py
index b89a4c960..7cb897e7d 100644
--- a/sphinx/util/template.py
+++ b/sphinx/util/template.py
@@ -44,6 +44,10 @@ class SphinxRenderer(FileRenderer):
     def __init__(self):
         super(SphinxRenderer, self).__init__(os.path.join(package_dir, 'templates'))
 
+    @classmethod
+    def render_from_file(cls, filename, context):
+        return FileRenderer.render_from_file(filename, context)
+
 
 class LaTeXRenderer(SphinxRenderer):
     def __init__(self):