diff --git a/doc/ext/githubpages.rst b/doc/ext/githubpages.rst new file mode 100644 index 000000000..0cd76a2c9 --- /dev/null +++ b/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. diff --git a/doc/extensions.rst b/doc/extensions.rst index 8347f4965..47632e593 100644 --- a/doc/extensions.rst +++ b/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 diff --git a/sphinx/ext/githubpages.py b/sphinx/ext/githubpages.py new file mode 100644 index 000000000..17b858a32 --- /dev/null +++ b/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} diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index f4514a2b2..471aa3bdf 100644 --- a/sphinx/quickstart.py +++ b/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 diff --git a/tests/roots/test-ext-githubpages/conf.py b/tests/roots/test-ext-githubpages/conf.py new file mode 100644 index 000000000..a05848fa6 --- /dev/null +++ b/tests/roots/test-ext-githubpages/conf.py @@ -0,0 +1,4 @@ +# -*- coding: utf-8 -*- + +extensions = ['sphinx.ext.githubpages'] +master_doc = 'index' diff --git a/tests/roots/test-ext-githubpages/index.rst b/tests/roots/test-ext-githubpages/index.rst new file mode 100644 index 000000000..711847f80 --- /dev/null +++ b/tests/roots/test-ext-githubpages/index.rst @@ -0,0 +1,3 @@ +githubpages +=========== + diff --git a/tests/test_ext_githubpages.py b/tests/test_ext_githubpages.py new file mode 100644 index 000000000..00a3b77e4 --- /dev/null +++ b/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() diff --git a/tests/test_quickstart.py b/tests/test_quickstart.py index 45ff8671d..156bf49e1 100644 --- a/tests/test_quickstart.py +++ b/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',