githubpages: support custom domains

Github Pages allows you to link a custom domain to your Github Pages
site by adding a `CNAME` file at the top-level of your `docs` directory.
The `githubpages` extension already inserts a `.nojekyll` file in the
`docs` directory, so it's a good place to add support for this `CNAME`
file as well.

1 files changed, 13 insertions, 4 deletions

diff --git a/sphinx/ext/githubpages.py b/sphinx/ext/githubpages.py
index f39d1cb58..5cecddd09 100644
--- a/sphinx/ext/githubpages.py
+++ b/sphinx/ext/githubpages.py
@@ -9,6 +9,7 @@
 """
 
 import os
+import urllib
 
 import sphinx
 
@@ -19,14 +20,22 @@ if False:
     from sphinx.environment import BuildEnvironment  # NOQA
 
 
-def create_nojekyll(app, env):
+def create_nojekyll_and_cname(app, env):
     # type: (Sphinx, BuildEnvironment) -> None
     if app.builder.format == 'html':
-        path = os.path.join(app.builder.outdir, '.nojekyll')
-        open(path, 'wt').close()
+        open(os.path.join(app.builder.outdir, '.nojekyll'), 'wt').close()
+
+        html_baseurl = app.config.html_baseurl
+        if html_baseurl:
+            domain = urllib.parse.urlparse(html_baseurl).hostname
+            if domain and not domain.endswith(".github.io"):
+                with open(os.path.join(app.builder.outdir, 'CNAME'), 'wt') as f:
+                    # NOTE: don't write a trailing newline. The `CNAME` file that's
+                    # auto-generated by the Github UI doesn't have one.
+                    f.write(domain)
 
 
 def setup(app):
     # type: (Sphinx) -> Dict[str, Any]
-    app.connect('env-updated', create_nojekyll)
+    app.connect('env-updated', create_nojekyll_and_cname)
     return {'version': sphinx.__display_version__, 'parallel_read_safe': True}