Add sphinx.ext.githubpages to publish the docs on GitHub Pages

doc/ext/githubpages.rst

@@ -0,0 +1,12 @@
+.. highlight:: rest
+
+:mod:`sphinx.ext.githubpages` -- Publish HTML docs in GitHub Pages
+==================================================================
+
+.. module:: sphinx.ext.githubpages
+   :synopsis: Publish HTML docs in GitHub Pages
+
+.. versionadded:: 1.4
+
+This extension creates ``.nojekyll`` file on generated HTML directory to publish
+the document on GitHub Pages.

doc/extensions.rst

@@ -32,6 +32,7 @@ These extensions are built in and can be activated by respective entries in the
    ext/viewcode
    ext/linkcode
    ext/napoleon
+   ext/githubpages
 
 
 Third-party extensions

sphinx/ext/githubpages.py

@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinx.ext.githubpages
+    ~~~~~~~~~~~~~~~~~~~~~~
+
+    To publish HTML docs at GitHub Pages, create .nojekyll file.
+
+    :copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+import os
+import sphinx
+
+
+def create_nojekyll(app, env):
+    if app.builder.format == 'html':
+        path = os.path.join(app.builder.outdir, '.nojekyll')
+        open(path, 'wt').close()
+
+
+def setup(app):
+    app.connect('env-updated', create_nojekyll)
+    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}

sphinx/quickstart.py

@@ -60,7 +60,7 @@ DEFAULT_VALUE = {
 }
 
 EXTENSIONS = ('autodoc', 'doctest', 'intersphinx', 'todo', 'coverage',
-              'imgmath', 'mathjax', 'ifconfig', 'viewcode')
+              'imgmath', 'mathjax', 'ifconfig', 'viewcode', 'githubpages')
 
 PROMPT_PREFIX = '> '
 
@@ -1271,6 +1271,9 @@ imgmath has been deselected.''')
     if 'ext_viewcode' not in d:
         do_prompt(d, 'ext_viewcode', 'viewcode: include links to the source '
                   'code of documented Python objects (y/n)', 'n', boolean)
+    if 'ext_githubpages' not in d:
+        do_prompt(d, 'ext_githubpages', 'githubpages: create .nojekyll file '
+                  'to publish the document on GitHub pages (y/n)', 'n', boolean)
 
     if 'no_makefile' in d:
         d['makefile'] = False

tests/roots/test-ext-githubpages/conf.py

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+
+extensions = ['sphinx.ext.githubpages']
+master_doc = 'index'

tests/roots/test-ext-githubpages/index.rst

@@ -0,0 +1,3 @@
+githubpages
+===========
+

tests/test_ext_githubpages.py

@@ -0,0 +1,20 @@
+# -*- coding: utf-8 -*-
+"""
+    test_ext_githubpages
+    ~~~~~~~~~~~~~~~~~~~~
+
+    Test sphinx.ext.githubpages extension.
+
+    :copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+import re
+
+from util import with_app
+
+
+@with_app('html', testroot='ext-githubpages')
+def test_githubpages(app, status, warning):
+    app.builder.build_all()
+    assert (app.outdir / '.nojekyll').exists()

tests/test_quickstart.py

@@ -185,6 +185,7 @@ def test_quickstart_all_answers(tempdir):
         'mathjax': 'no',
         'ifconfig': 'no',
         'viewcode': 'no',
+        'githubpages': 'no',
         'Create Makefile': 'no',
         'Create Windows command file': 'no',
         'Do you want to use the epub builder': 'yes',