sphinx/ext/githubpages.py


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

"""To publish HTML docs at GitHub Pages, create .nojekyll file.
"""

import os
import urllib
from typing import Any, Dict

import sphinx
from sphinx.application import Sphinx
from sphinx.environment import BuildEnvironment


def create_nojekyll_and_cname(app: Sphinx, env: BuildEnvironment) -> None:
    if app.builder.format == 'html':
        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: Sphinx) -> Dict[str, Any]:
    app.connect('env-updated', create_nojekyll_and_cname)
    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}