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.

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}

tests/test_ext_githubpages.py

@@ -15,3 +15,18 @@ import pytest
 def test_githubpages(app, status, warning):
     app.builder.build_all()
     assert (app.outdir / '.nojekyll').exists()
+    assert not (app.outdir / 'CNAME').exists()
+
+
+@pytest.mark.sphinx('html', testroot='ext-githubpages', confoverrides={'html_baseurl': 'https://sphinx-doc.github.io'})
+def test_no_cname_for_github_io_domain(app, status, warning):
+    app.builder.build_all()
+    assert (app.outdir / '.nojekyll').exists()
+    assert not (app.outdir / 'CNAME').exists()
+
+
+@pytest.mark.sphinx('html', testroot='ext-githubpages', confoverrides={'html_baseurl': 'https://sphinx-doc.org'})
+def test_cname_for_custom_domain(app, status, warning):
+    app.builder.build_all()
+    assert (app.outdir / '.nojekyll').exists()
+    assert (app.outdir / 'CNAME').text() == 'sphinx-doc.org'