Sphinx 8.1.3__py3-none-any.whl → 8.2.0__py3-none-any.whl

sphinx/builders/_epub_base.py

@@ -4,10 +4,11 @@ from __future__ import annotations
 
 import html
 import os
+import os.path
 import re
 import time
-from os import path
-from typing import TYPE_CHECKING, Any, NamedTuple
+from pathlib import Path
+from typing import TYPE_CHECKING, NamedTuple
 from urllib.parse import quote
 from zipfile import ZIP_DEFLATED, ZIP_STORED, ZipFile
 
@@ -19,11 +20,14 @@ from sphinx.builders.html import StandaloneHTMLBuilder
 from sphinx.builders.html._build_info import BuildInfo
 from sphinx.locale import __
 from sphinx.util import logging
+from sphinx.util._pathlib import _StrPath
 from sphinx.util.display import status_iterator
 from sphinx.util.fileutil import copy_asset_file
 from sphinx.util.osutil import copyfile, ensuredir, relpath
 
 if TYPE_CHECKING:
+    from typing import Any
+
     from docutils.nodes import Element, Node
 
 try:
@@ -123,8 +127,7 @@ ssp = sphinx_smarty_pants
 
 
 class EpubBuilder(StandaloneHTMLBuilder):
-    """
-    Builder that outputs epub files.
+    """Builder that outputs epub files.
 
     It creates the metainfo files container.opf, toc.ncx, mimetype, and
     META-INF/container.xml.  Afterwards, all necessary files are zipped to an
@@ -156,7 +159,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
     guide_titles = GUIDE_TITLES
     media_types = MEDIA_TYPES
     refuri_re = REFURI_RE
-    template_dir = ''
+    template_dir: _StrPath = _StrPath()
     doctype = ''
 
     def init(self) -> None:
@@ -226,18 +229,16 @@ class EpubBuilder(StandaloneHTMLBuilder):
                 appeared.add(node['refuri'])
 
     def get_toc(self) -> None:
-        """Get the total table of contents, containing the root_doc
-        and pre and post files not managed by sphinx.
+        """Get the total table of contents, containing the master_doc
+        and pre and post files not managed by Sphinx.
         """
         doctree = self.env.get_and_resolve_doctree(
-            self.config.root_doc, self, prune_toctrees=False, includehidden=True
+            self.config.master_doc, self, prune_toctrees=False, includehidden=True
         )
         self.refnodes = self.get_refnodes(doctree, [])
-        master_dir = path.dirname(self.config.root_doc)
-        if master_dir:
-            master_dir += '/'  # XXX or os.sep?
-            for item in self.refnodes:
-                item['refuri'] = master_dir + item['refuri']
+        master_dir = Path(self.config.master_doc).parent
+        for item in self.refnodes:
+            item['refuri'] = str(master_dir / item['refuri'])
         self.toc_add_files(self.refnodes)
 
     def toc_add_files(self, refnodes: list[dict[str, Any]]) -> None:
@@ -407,7 +408,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
 
     def is_vector_graphics(self, filename: str) -> bool:
         """Does the filename extension indicate a vector graphic format?"""
-        ext = path.splitext(filename)[-1]
+        ext = os.path.splitext(filename)[-1]
         return ext in VECTOR_GRAPHICS_EXTENSIONS
 
     def copy_image_files_pil(self) -> None:
@@ -415,7 +416,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
         The method tries to read and write the files with Pillow, converting
         the format and resizing the image if necessary/possible.
         """
-        ensuredir(path.join(self.outdir, self.imagedir))
+        ensuredir(self.outdir / self.imagedir)
         for src in status_iterator(
             self.images,
             __('copying images... '),
@@ -425,12 +426,12 @@ class EpubBuilder(StandaloneHTMLBuilder):
         ):
             dest = self.images[src]
             try:
-                img = Image.open(path.join(self.srcdir, src))
+                img = Image.open(self.srcdir / src)
             except OSError:
                 if not self.is_vector_graphics(src):
                     logger.warning(
                         __('cannot read image file %r: copying it instead'),
-                        path.join(self.srcdir, src),
+                        self.srcdir / src,
                     )
                 try:
                     copyfile(
@@ -441,7 +442,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
                 except OSError as err:
                     logger.warning(
                         __('cannot copy image file %r: %s'),
-                        path.join(self.srcdir, src),
+                        self.srcdir / src,
                         err,
                     )
                 continue
@@ -457,11 +458,11 @@ class EpubBuilder(StandaloneHTMLBuilder):
                     nh = round((height * nw) / width)
                     img = img.resize((nw, nh), Image.BICUBIC)
             try:
-                img.save(path.join(self.outdir, self.imagedir, dest))
+                img.save(self.outdir / self.imagedir / dest)
             except OSError as err:
                 logger.warning(
                     __('cannot write image file %r: %s'),
-                    path.join(self.srcdir, src),
+                    self.srcdir / src,
                     err,
                 )
 
@@ -487,7 +488,8 @@ class EpubBuilder(StandaloneHTMLBuilder):
         pagename: str,
         addctx: dict[str, Any],
         templatename: str = 'page.html',
-        outfilename: str | None = None,
+        *,
+        outfilename: Path | None = None,
         event_arg: Any = None,
     ) -> None:
         """Create a rendered page.
@@ -500,13 +502,15 @@ class EpubBuilder(StandaloneHTMLBuilder):
                 return
             self.fix_genindex(addctx['genindexentries'])
         addctx['doctype'] = self.doctype
-        super().handle_page(pagename, addctx, templatename, outfilename, event_arg)
+        super().handle_page(
+            pagename, addctx, templatename, outfilename=outfilename, event_arg=event_arg
+        )
 
     def build_mimetype(self) -> None:
         """Write the metainfo file mimetype."""
         logger.info(__('writing mimetype file...'))
         copyfile(
-            path.join(self.template_dir, 'mimetype'),
+            self.template_dir / 'mimetype',
             self.outdir / 'mimetype',
             force=True,
         )
@@ -517,7 +521,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
         outdir = self.outdir / 'META-INF'
         ensuredir(outdir)
         copyfile(
-            path.join(self.template_dir, 'container.xml'),
+            self.template_dir / 'container.xml',
             outdir / 'container.xml',
             force=True,
         )
@@ -531,19 +535,20 @@ class EpubBuilder(StandaloneHTMLBuilder):
         else:
             time_tuple = time.gmtime()
 
-        metadata: dict[str, Any] = {}
-        metadata['title'] = html.escape(self.config.epub_title)
-        metadata['author'] = html.escape(self.config.epub_author)
-        metadata['uid'] = html.escape(self.config.epub_uid)
-        metadata['lang'] = html.escape(self.config.epub_language)
-        metadata['publisher'] = html.escape(self.config.epub_publisher)
-        metadata['copyright'] = html.escape(self.config.epub_copyright)
-        metadata['scheme'] = html.escape(self.config.epub_scheme)
-        metadata['id'] = html.escape(self.config.epub_identifier)
-        metadata['date'] = html.escape(time.strftime('%Y-%m-%d', time_tuple))
-        metadata['manifest_items'] = []
-        metadata['spines'] = []
-        metadata['guides'] = []
+        metadata: dict[str, Any] = {
+            'title': html.escape(self.config.epub_title),
+            'author': html.escape(self.config.epub_author),
+            'uid': html.escape(self.config.epub_uid),
+            'lang': html.escape(self.config.epub_language),
+            'publisher': html.escape(self.config.epub_publisher),
+            'copyright': html.escape(self.config.epub_copyright),
+            'scheme': html.escape(self.config.epub_scheme),
+            'id': html.escape(self.config.epub_identifier),
+            'date': html.escape(time.strftime('%Y-%m-%d', time_tuple)),
+            'manifest_items': [],
+            'spines': [],
+            'guides': [],
+        }
         return metadata
 
     def build_content(self) -> None:
@@ -571,16 +576,17 @@ class EpubBuilder(StandaloneHTMLBuilder):
         if not self.use_index:
             self.ignored_files.append('genindex' + self.out_suffix)
         for root, dirs, files in os.walk(self.outdir):
+            root_path = Path(root)
             dirs.sort()
             for fn in sorted(files):
-                filename = relpath(path.join(root, fn), self.outdir)
+                filename = relpath(root_path / fn, self.outdir)
                 if filename in self.ignored_files:
                     continue
-                ext = path.splitext(filename)[-1]
+                ext = os.path.splitext(filename)[-1]
                 if ext not in self.media_types:
                     # we always have JS and potentially OpenSearch files, don't
                     # always warn about them
-                    if ext not in ('.js', '.xml'):
+                    if ext not in {'.js', '.xml'}:
                         logger.warning(
                             __('unknown mimetype for %s, ignoring'),
                             filename,
@@ -631,7 +637,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
                 spine = Spine(html.escape(self.make_id(self.coverpage_name)), True)
                 metadata['spines'].insert(0, spine)
                 if self.coverpage_name not in self.files:
-                    ext = path.splitext(self.coverpage_name)[-1]
+                    ext = os.path.splitext(self.coverpage_name)[-1]
                     self.files.append(self.coverpage_name)
                     item = ManifestItem(
                         html.escape(self.coverpage_name),
@@ -640,7 +646,9 @@ class EpubBuilder(StandaloneHTMLBuilder):
                     )
                     metadata['manifest_items'].append(item)
                 ctx = {'image': html.escape(image), 'title': self.config.project}
-                self.handle_page(path.splitext(self.coverpage_name)[0], ctx, html_tmpl)
+                self.handle_page(
+                    os.path.splitext(self.coverpage_name)[0], ctx, html_tmpl
+                )
                 spinefiles.add(self.coverpage_name)
 
         auto_add_cover = True
@@ -676,7 +684,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
 
         # write the project file
         copy_asset_file(
-            path.join(self.template_dir, 'content.opf.jinja'),
+            self.template_dir / 'content.opf.jinja',
             self.outdir,
             context=metadata,
             force=True,
@@ -700,8 +708,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
         Subelements of a node are nested inside the navpoint.  For nested nodes
         the parent node is reinserted in the subnav.
         """
-        navstack: list[NavPoint] = []
-        navstack.append(NavPoint('dummy', 0, '', '', []))
+        navstack: list[NavPoint] = [NavPoint('dummy', 0, '', '', [])]
         level = 0
         lastnode = None
         for node in nodes:
@@ -735,7 +742,8 @@ class EpubBuilder(StandaloneHTMLBuilder):
                 navstack[-1].children.append(navpoint)
                 navstack.append(navpoint)
             else:
-                raise
+                msg = __('node has an invalid level')
+                raise ValueError(msg)
             lastnode = node
 
         return navstack[0].children
@@ -744,11 +752,12 @@ class EpubBuilder(StandaloneHTMLBuilder):
         """Create a dictionary with all metadata for the toc.ncx file
         properly escaped.
         """
-        metadata: dict[str, Any] = {}
-        metadata['uid'] = self.config.epub_uid
-        metadata['title'] = html.escape(self.config.epub_title)
-        metadata['level'] = level
-        metadata['navpoints'] = navpoints
+        metadata: dict[str, Any] = {
+            'uid': self.config.epub_uid,
+            'title': html.escape(self.config.epub_title),
+            'level': level,
+            'navpoints': navpoints,
+        }
         return metadata
 
     def build_toc(self) -> None:
@@ -769,7 +778,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
         level = max(item['level'] for item in self.refnodes)
         level = min(level, self.config.epub_tocdepth)
         copy_asset_file(
-            path.join(self.template_dir, 'toc.ncx.jinja'),
+            self.template_dir / 'toc.ncx.jinja',
             self.outdir,
             context=self.toc_metadata(level, navpoints),
             force=True,
@@ -783,10 +792,10 @@ class EpubBuilder(StandaloneHTMLBuilder):
         """
         outname = self.config.epub_basename + '.epub'
         logger.info(__('writing %s file...'), outname)
-        epub_filename = path.join(self.outdir, outname)
+        epub_filename = self.outdir / outname
         with ZipFile(epub_filename, 'w', ZIP_DEFLATED) as epub:
-            epub.write(path.join(self.outdir, 'mimetype'), 'mimetype', ZIP_STORED)
+            epub.write(self.outdir / 'mimetype', 'mimetype', ZIP_STORED)
             for filename in ('META-INF/container.xml', 'content.opf', 'toc.ncx'):
-                epub.write(path.join(self.outdir, filename), filename, ZIP_DEFLATED)
+                epub.write(self.outdir / filename, filename, ZIP_DEFLATED)
             for filename in self.files:
-                epub.write(path.join(self.outdir, filename), filename, ZIP_DEFLATED)
+                epub.write(self.outdir / filename, filename, ZIP_DEFLATED)

sphinx/builders/changes.py

@@ -3,17 +3,15 @@
 from __future__ import annotations
 
 import html
-from os import path
 from typing import TYPE_CHECKING
 
 from sphinx import package_dir
+from sphinx._cli.util.colour import bold
 from sphinx.builders import Builder
 from sphinx.locale import _, __
 from sphinx.theming import HTMLThemeFactory
 from sphinx.util import logging
-from sphinx.util.console import bold
 from sphinx.util.fileutil import copy_asset_file
-from sphinx.util.osutil import ensuredir, os_path
 
 if TYPE_CHECKING:
     from collections.abc import Set
@@ -25,9 +23,7 @@ logger = logging.getLogger(__name__)
 
 
 class ChangesBuilder(Builder):
-    """
-    Write a summary with all versionadded/changed/deprecated/removed directives.
-    """
+    """Write a summary with all versionadded/changed/deprecated/removed directives."""
 
     name = 'changes'
     epilog = __('The overview file is in %(outdir)s.')
@@ -61,10 +57,7 @@ class ChangesBuilder(Builder):
             return
         logger.info(bold(__('writing summary file...')))
         for changeset in changesets:
-            if isinstance(changeset.descname, tuple):
-                descname = changeset.descname[0]
-            else:
-                descname = changeset.descname
+            descname = changeset.descname
             ttext = self.typemap[changeset.type]
             context = changeset.content.replace('\n', ' ')
             if descname and changeset.docname.startswith('c-api'):
@@ -108,9 +101,9 @@ class ChangesBuilder(Builder):
             'show_copyright': self.config.html_show_copyright,
             'show_sphinx': self.config.html_show_sphinx,
         }
-        with open(path.join(self.outdir, 'index.html'), 'w', encoding='utf8') as f:
+        with open(self.outdir / 'index.html', 'w', encoding='utf8') as f:
             f.write(self.templates.render('changes/frameset.html', ctx))
-        with open(path.join(self.outdir, 'changes.html'), 'w', encoding='utf8') as f:
+        with open(self.outdir / 'changes.html', 'w', encoding='utf8') as f:
             f.write(self.templates.render('changes/versionchanges.html', ctx))
 
         hltext = [
@@ -131,7 +124,7 @@ class ChangesBuilder(Builder):
         logger.info(bold(__('copying source files...')))
         for docname in self.env.all_docs:
             with open(
-                self.env.doc2path(docname), encoding=self.env.config.source_encoding
+                self.env.doc2path(docname), encoding=self.config.source_encoding
             ) as f:
                 try:
                     lines = f.readlines()
@@ -140,27 +133,28 @@ class ChangesBuilder(Builder):
                         __('could not read %r for changelog creation'), docname
                     )
                     continue
-            targetfn = path.join(self.outdir, 'rst', os_path(docname)) + '.html'
-            ensuredir(path.dirname(targetfn))
+            text = ''.join(hl(i + 1, line) for (i, line) in enumerate(lines))
+            ctx = {
+                'filename': str(self.env.doc2path(docname, False)),
+                'text': text,
+            }
+            rendered = self.templates.render('changes/rstsource.html', ctx)
+            targetfn = self.outdir / 'rst' / f'{docname}.html'
+            targetfn.parent.mkdir(parents=True, exist_ok=True)
             with open(targetfn, 'w', encoding='utf-8') as f:
-                text = ''.join(hl(i + 1, line) for (i, line) in enumerate(lines))
-                ctx = {
-                    'filename': str(self.env.doc2path(docname, False)),
-                    'text': text,
-                }
-                f.write(self.templates.render('changes/rstsource.html', ctx))
+                f.write(rendered)
         themectx = {
             'theme_' + key: val for (key, val) in self.theme.get_options({}).items()
         }
         copy_asset_file(
-            path.join(package_dir, 'themes', 'default', 'static', 'default.css.jinja'),
+            package_dir.joinpath('themes', 'default', 'static', 'default.css.jinja'),
             self.outdir,
             context=themectx,
             renderer=self.templates,
             force=True,
         )
         copy_asset_file(
-            path.join(package_dir, 'themes', 'basic', 'static', 'basic.css'),
+            package_dir.joinpath('themes', 'basic', 'static', 'basic.css'),
             self.outdir / 'basic.css',
             force=True,
         )

sphinx/builders/dirhtml.py

@@ -2,12 +2,12 @@
 
 from __future__ import annotations
 
-from os import path
+from pathlib import Path
 from typing import TYPE_CHECKING
 
 from sphinx.builders.html import StandaloneHTMLBuilder
 from sphinx.util import logging
-from sphinx.util.osutil import SEP, os_path
+from sphinx.util.osutil import SEP
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
@@ -17,8 +17,7 @@ logger = logging.getLogger(__name__)
 
 
 class DirectoryHTMLBuilder(StandaloneHTMLBuilder):
-    """
-    A StandaloneHTMLBuilder that creates all HTML pages as "index.html" in
+    """A StandaloneHTMLBuilder that creates all HTML pages as "index.html" in
     a directory given by their pagename, so that generated URLs don't have
     ``.html`` in them.
     """
@@ -32,15 +31,11 @@ class DirectoryHTMLBuilder(StandaloneHTMLBuilder):
             return docname[:-5]  # up to sep
         return docname + SEP
 
-    def get_outfilename(self, pagename: str) -> str:
-        if pagename == 'index' or pagename.endswith(SEP + 'index'):
-            outfilename = path.join(self.outdir, os_path(pagename) + self.out_suffix)
-        else:
-            outfilename = path.join(
-                self.outdir, os_path(pagename), 'index' + self.out_suffix
-            )
-
-        return outfilename
+    def get_output_path(self, page_name: str, /) -> Path:
+        page_parts = page_name.split(SEP)
+        if page_parts[-1] == 'index':
+            page_parts.pop()
+        return Path(self.outdir, *page_parts, f'index{self.out_suffix}')
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:

sphinx/builders/epub3.py

@@ -7,14 +7,14 @@ from __future__ import annotations
 
 import html
 import os
+import os.path
 import re
 import time
-from os import path
-from typing import TYPE_CHECKING, Any, NamedTuple
+from typing import TYPE_CHECKING, NamedTuple
 
 from sphinx import package_dir
 from sphinx.builders import _epub_base
-from sphinx.config import ENUM, Config
+from sphinx.config import ENUM
 from sphinx.locale import __
 from sphinx.util import logging
 from sphinx.util.fileutil import copy_asset_file
@@ -22,8 +22,10 @@ from sphinx.util.osutil import make_filename
 
 if TYPE_CHECKING:
     from collections.abc import Set
+    from typing import Any
 
     from sphinx.application import Sphinx
+    from sphinx.config import Config
     from sphinx.util.typing import ExtensionMetadata
 
 logger = logging.getLogger(__name__)
@@ -65,14 +67,13 @@ _xml_name_start_char = (
     '|[\ufdf0-\ufffd]|[\U00010000-\U000effff]'
 )
 _xml_name_char = (
-    _xml_name_start_char + r'\-|\.' '|[0-9]|\u00b7|[\u0300-\u036f]|[\u203f-\u2040]'
+    _xml_name_start_char + r'\-|\.|[0-9]|\u00b7|[\u0300-\u036f]|[\u203f-\u2040]'
 )
 _XML_NAME_PATTERN = re.compile(f'({_xml_name_start_char})({_xml_name_char})*')
 
 
 class Epub3Builder(_epub_base.EpubBuilder):
-    """
-    Builder that outputs epub3 files.
+    """Builder that outputs epub3 files.
 
     It creates the metainfo files content.opf, nav.xhtml, toc.ncx, mimetype,
     and META-INF/container.xml. Afterwards, all necessary files are zipped to
@@ -83,7 +84,7 @@ class Epub3Builder(_epub_base.EpubBuilder):
     epilog = __('The ePub file is in %(outdir)s.')
 
     supported_remote_images = False
-    template_dir = path.join(package_dir, 'templates', 'epub3')
+    template_dir = package_dir.joinpath('templates', 'epub3')
     doctype = DOCTYPE
     html_tag = HTML_TAG
     use_meta_charset = True
@@ -141,8 +142,7 @@ class Epub3Builder(_epub_base.EpubBuilder):
         The difference from build_navpoints method is templates which are used
         when generating navigation documents.
         """
-        navstack: list[NavPoint] = []
-        navstack.append(NavPoint('', '', []))
+        navstack: list[NavPoint] = [NavPoint('', '', [])]
         level = 0
         for node in navnodes:
             if not node['text']:
@@ -199,7 +199,7 @@ class Epub3Builder(_epub_base.EpubBuilder):
             refnodes = self.refnodes
         navlist = self.build_navlist(refnodes)
         copy_asset_file(
-            path.join(self.template_dir, 'nav.xhtml.jinja'),
+            self.template_dir / 'nav.xhtml.jinja',
             self.outdir,
             context=self.navigation_doc_metadata(navlist),
             force=True,
@@ -286,35 +286,67 @@ def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_builder(Epub3Builder)
 
     # config values
-    app.add_config_value('epub_basename', lambda self: make_filename(self.project), '')
-    app.add_config_value('epub_version', 3.0, 'epub')  # experimental
-    app.add_config_value('epub_theme', 'epub', 'epub')
-    app.add_config_value('epub_theme_options', {}, 'epub')
-    app.add_config_value('epub_title', lambda self: self.project, 'epub')
-    app.add_config_value('epub_author', lambda self: self.author, 'epub')
-    app.add_config_value('epub_language', lambda self: self.language or 'en', 'epub')
-    app.add_config_value('epub_publisher', lambda self: self.author, 'epub')
-    app.add_config_value('epub_copyright', lambda self: self.copyright, 'epub')
-    app.add_config_value('epub_identifier', 'unknown', 'epub')
-    app.add_config_value('epub_scheme', 'unknown', 'epub')
-    app.add_config_value('epub_uid', 'unknown', 'env')
-    app.add_config_value('epub_cover', (), 'env')
-    app.add_config_value('epub_guide', (), 'env')
-    app.add_config_value('epub_pre_files', [], 'env')
-    app.add_config_value('epub_post_files', [], 'env')
-    app.add_config_value('epub_css_files', lambda config: config.html_css_files, 'epub')
-    app.add_config_value('epub_exclude_files', [], 'env')
-    app.add_config_value('epub_tocdepth', 3, 'env')
-    app.add_config_value('epub_tocdup', True, 'env')
-    app.add_config_value('epub_tocscope', 'default', 'env')
-    app.add_config_value('epub_fix_images', False, 'env')
-    app.add_config_value('epub_max_image_width', 0, 'env')
-    app.add_config_value('epub_show_urls', 'inline', 'epub')
-    app.add_config_value('epub_use_index', lambda self: self.html_use_index, 'epub')
-    app.add_config_value('epub_description', 'unknown', 'epub')
-    app.add_config_value('epub_contributor', 'unknown', 'epub')
     app.add_config_value(
-        'epub_writing_mode', 'horizontal', 'epub', ENUM('horizontal', 'vertical')
+        'epub_basename',
+        lambda self: make_filename(self.project),
+        '',
+        types=frozenset({str}),
+    )
+    app.add_config_value(
+        'epub_version', 3.0, 'epub', types=frozenset({float})
+    )  # experimental
+    app.add_config_value('epub_theme', 'epub', 'epub', types=frozenset({str}))
+    app.add_config_value('epub_theme_options', {}, 'epub', types=frozenset({dict}))
+    app.add_config_value(
+        'epub_title', lambda self: self.project, 'epub', types=frozenset({str})
+    )
+    app.add_config_value(
+        'epub_author', lambda self: self.author, 'epub', types=frozenset({str})
+    )
+    app.add_config_value(
+        'epub_language',
+        lambda self: self.language or 'en',
+        'epub',
+        types=frozenset({str}),
+    )
+    app.add_config_value(
+        'epub_publisher', lambda self: self.author, 'epub', types=frozenset({str})
+    )
+    app.add_config_value(
+        'epub_copyright', lambda self: self.copyright, 'epub', types=frozenset({str})
+    )
+    app.add_config_value('epub_identifier', 'unknown', 'epub', types=frozenset({str}))
+    app.add_config_value('epub_scheme', 'unknown', 'epub', types=frozenset({str}))
+    app.add_config_value('epub_uid', 'unknown', 'env', types=frozenset({str}))
+    app.add_config_value('epub_cover', (), 'env', types=frozenset({list, tuple}))
+    app.add_config_value('epub_guide', (), 'env', types=frozenset({list, tuple}))
+    app.add_config_value('epub_pre_files', [], 'env', types=frozenset({list, tuple}))
+    app.add_config_value('epub_post_files', [], 'env', types=frozenset({list, tuple}))
+    app.add_config_value(
+        'epub_css_files',
+        lambda config: config.html_css_files,
+        'epub',
+        types=frozenset({list, tuple}),
+    )
+    app.add_config_value(
+        'epub_exclude_files', [], 'env', types=frozenset({list, tuple})
+    )
+    app.add_config_value('epub_tocdepth', 3, 'env', types=frozenset({int}))
+    app.add_config_value('epub_tocdup', True, 'env', types=frozenset({bool}))
+    app.add_config_value('epub_tocscope', 'default', 'env', types=frozenset({str}))
+    app.add_config_value('epub_fix_images', False, 'env', types=frozenset({bool}))
+    app.add_config_value('epub_max_image_width', 0, 'env', types=frozenset({int}))
+    app.add_config_value('epub_show_urls', 'inline', 'epub', types=frozenset({str}))
+    app.add_config_value(
+        'epub_use_index',
+        lambda self: self.html_use_index,
+        'epub',
+        types=frozenset({bool}),
+    )
+    app.add_config_value('epub_description', 'unknown', 'epub', types=frozenset({str}))
+    app.add_config_value('epub_contributor', 'unknown', 'epub', types=frozenset({str}))
+    app.add_config_value(
+        'epub_writing_mode', 'horizontal', 'epub', types=ENUM('horizontal', 'vertical')
     )
 
     # event handlers