1""" 2 sphinx.builders.dirhtml 3 ~~~~~~~~~~~~~~~~~~~~~~~ 4 5 Directory HTML builders. 6 7 :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. 8 :license: BSD, see LICENSE for details. 9""" 10 11from os import path 12from typing import Any, Dict 13 14from sphinx.application import Sphinx 15from sphinx.builders.html import StandaloneHTMLBuilder 16from sphinx.deprecation import RemovedInSphinx40Warning, deprecated_alias 17from sphinx.util import logging 18from sphinx.util.osutil import SEP, os_path 19 20logger = logging.getLogger(__name__) 21 22 23class DirectoryHTMLBuilder(StandaloneHTMLBuilder): 24 """ 25 A StandaloneHTMLBuilder that creates all HTML pages as "index.html" in 26 a directory given by their pagename, so that generated URLs don't have 27 ``.html`` in them. 28 """ 29 name = 'dirhtml' 30 31 def get_target_uri(self, docname: str, typ: str = None) -> str: 32 if docname == 'index': 33 return '' 34 if docname.endswith(SEP + 'index'): 35 return docname[:-5] # up to sep 36 return docname + SEP 37 38 def get_outfilename(self, pagename: str) -> str: 39 if pagename == 'index' or pagename.endswith(SEP + 'index'): 40 outfilename = path.join(self.outdir, os_path(pagename) + 41 self.out_suffix) 42 else: 43 outfilename = path.join(self.outdir, os_path(pagename), 44 'index' + self.out_suffix) 45 46 return outfilename 47 48 49# for compatibility 50deprecated_alias('sphinx.builders.html', 51 { 52 'DirectoryHTMLBuilder': DirectoryHTMLBuilder, 53 }, 54 RemovedInSphinx40Warning, 55 { 56 'DirectoryHTMLBuilder': 'sphinx.builders.dirhtml.DirectoryHTMLBuilder', 57 }) 58 59 60def setup(app: Sphinx) -> Dict[str, Any]: 61 app.setup_extension('sphinx.builders.html') 62 63 app.add_builder(DirectoryHTMLBuilder) 64 65 return { 66 'version': 'builtin', 67 'parallel_read_safe': True, 68 'parallel_write_safe': True, 69 } 70