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

sphinx/builders/linkcheck.py

@@ -7,29 +7,34 @@ import json
 import re
 import socket
 import time
+from enum import StrEnum
 from html.parser import HTMLParser
-from os import path
 from queue import PriorityQueue, Queue
 from threading import Thread
 from typing import TYPE_CHECKING, NamedTuple, cast
 from urllib.parse import quote, unquote, urlparse, urlsplit, urlunparse
 
 from docutils import nodes
-from requests.exceptions import ConnectionError, HTTPError, SSLError, TooManyRedirects
+from requests.exceptions import (
+    ConnectionError,  # NoQA: A004
+    HTTPError,
+    SSLError,
+    TooManyRedirects,
+)
 from requests.exceptions import Timeout as RequestTimeout
 
+from sphinx._cli.util.colour import darkgray, darkgreen, purple, red, turquoise
 from sphinx.builders.dummy import DummyBuilder
 from sphinx.locale import __
 from sphinx.transforms.post_transforms import SphinxPostTransform
 from sphinx.util import logging, requests
 from sphinx.util._uri import encode_uri
-from sphinx.util.console import darkgray, darkgreen, purple, red, turquoise
 from sphinx.util.http_date import rfc1123_to_epoch
 from sphinx.util.nodes import get_node_line
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterator
-    from typing import Any
+    from typing import Any, Literal, TypeAlias
 
     from requests import Response
 
@@ -38,6 +43,20 @@ if TYPE_CHECKING:
     from sphinx.util._pathlib import _StrPath
     from sphinx.util.typing import ExtensionMetadata
 
+    _URIProperties: TypeAlias = tuple['_Status', str, int]
+
+
+class _Status(StrEnum):
+    BROKEN = 'broken'
+    IGNORED = 'ignored'
+    RATE_LIMITED = 'rate-limited'
+    REDIRECTED = 'redirected'
+    TIMEOUT = 'timeout'
+    UNCHECKED = 'unchecked'
+    UNKNOWN = 'unknown'
+    WORKING = 'working'
+
+
 logger = logging.getLogger(__name__)
 
 # matches to foo:// and // (a protocol relative URL)
@@ -52,9 +71,7 @@ DEFAULT_DELAY = 60.0
 
 
 class CheckExternalLinksBuilder(DummyBuilder):
-    """
-    Checks for broken external links.
-    """
+    """Checks for broken external links."""
 
     name = 'linkcheck'
     epilog = __('Look for any errors in the above output or in %(outdir)s/output.txt')
@@ -70,8 +87,8 @@ class CheckExternalLinksBuilder(DummyBuilder):
         checker = HyperlinkAvailabilityChecker(self.config)
         logger.info('')
 
-        output_text = path.join(self.outdir, 'output.txt')
-        output_json = path.join(self.outdir, 'output.json')
+        output_text = self.outdir / 'output.txt'
+        output_json = self.outdir / 'output.json'
         with (
             open(output_text, 'w', encoding='utf-8') as self.txt_outfile,
             open(output_json, 'w', encoding='utf-8') as self.json_outfile,
@@ -84,112 +101,107 @@ class CheckExternalLinksBuilder(DummyBuilder):
 
     def process_result(self, result: CheckResult) -> None:
         filename = self.env.doc2path(result.docname, False)
+        res_uri = result.uri
 
-        linkstat: dict[str, str | int] = {
+        linkstat: dict[str, str | int | _Status] = {
             'filename': str(filename),
             'lineno': result.lineno,
             'status': result.status,
             'code': result.code,
-            'uri': result.uri,
+            'uri': res_uri,
             'info': result.message,
         }
         self.write_linkstat(linkstat)
 
-        if result.status == 'unchecked':
-            return
-        if result.status == 'working' and result.message == 'old':
-            return
-        if result.lineno:
+        if result.lineno and result.status != _Status.UNCHECKED:
+            # unchecked links are not logged
             logger.info('(%16s: line %4d) ', result.docname, result.lineno, nonl=True)
-        if result.status == 'ignored':
-            if result.message:
-                logger.info(darkgray('-ignored- ') + result.uri + ': ' + result.message)
-            else:
-                logger.info(darkgray('-ignored- ') + result.uri)
-        elif result.status == 'local':
-            logger.info(darkgray('-local-   ') + result.uri)
-            self.write_entry(
-                'local', result.docname, filename, result.lineno, result.uri
-            )
-        elif result.status == 'working':
-            logger.info(darkgreen('ok        ') + result.uri + result.message)
-        elif result.status == 'timeout':
-            if self.app.quiet:
-                logger.warning(
-                    'timeout   ' + result.uri + result.message,
-                    location=(result.docname, result.lineno),
-                )
-            else:
-                logger.info(
-                    red('timeout   ') + result.uri + red(' - ' + result.message)
-                )
-            self.write_entry(
-                'timeout',
-                result.docname,
-                filename,
-                result.lineno,
-                result.uri + ': ' + result.message,
-            )
-            self.timed_out_hyperlinks += 1
-        elif result.status == 'broken':
-            if self.app.quiet:
-                logger.warning(
-                    __('broken link: %s (%s)'),
-                    result.uri,
-                    result.message,
-                    location=(result.docname, result.lineno),
-                )
-            else:
-                logger.info(
-                    red('broken    ') + result.uri + red(' - ' + result.message)
+
+        match result.status:
+            case _Status.RATE_LIMITED | _Status.UNCHECKED:
+                pass
+            case _Status.IGNORED:
+                if result.message:
+                    msg = f'{res_uri}: {result.message}'
+                else:
+                    msg = res_uri
+                logger.info(darkgray('-ignored- ') + msg)  # NoQA: G003
+            case _Status.WORKING:
+                logger.info(darkgreen('ok        ') + f'{res_uri}{result.message}')  # NoQA: G003
+            case _Status.TIMEOUT:
+                if self.app.quiet:
+                    msg = 'timeout   ' + f'{res_uri}{result.message}'
+                    logger.warning(msg, location=(result.docname, result.lineno))
+                else:
+                    msg = red('timeout   ') + res_uri + red(f' - {result.message}')
+                    logger.info(msg)
+                self.write_entry(
+                    _Status.TIMEOUT,
+                    result.docname,
+                    filename,
+                    result.lineno,
+                    f'{res_uri}: {result.message}',
                 )
-            self.write_entry(
-                'broken',
-                result.docname,
-                filename,
-                result.lineno,
-                result.uri + ': ' + result.message,
-            )
-            self.broken_hyperlinks += 1
-        elif result.status == 'redirected':
-            try:
-                text, color = {
-                    301: ('permanently', purple),
-                    302: ('with Found', purple),
-                    303: ('with See Other', purple),
-                    307: ('temporarily', turquoise),
-                    308: ('permanently', purple),
-                }[result.code]
-            except KeyError:
-                text, color = ('with unknown code', purple)
-            linkstat['text'] = text
-            if self.config.linkcheck_allowed_redirects:
-                logger.warning(
-                    'redirect  ' + result.uri + ' - ' + text + ' to ' + result.message,
-                    location=(result.docname, result.lineno),
+                self.timed_out_hyperlinks += 1
+            case _Status.BROKEN:
+                if self.app.quiet:
+                    logger.warning(
+                        __('broken link: %s (%s)'),
+                        res_uri,
+                        result.message,
+                        location=(result.docname, result.lineno),
+                    )
+                else:
+                    msg = red('broken    ') + res_uri + red(f' - {result.message}')
+                    logger.info(msg)
+                self.write_entry(
+                    _Status.BROKEN,
+                    result.docname,
+                    filename,
+                    result.lineno,
+                    f'{res_uri}: {result.message}',
                 )
-            else:
-                logger.info(
-                    color('redirect  ')
-                    + result.uri
-                    + color(' - ' + text + ' to ' + result.message)
+                self.broken_hyperlinks += 1
+            case _Status.REDIRECTED:
+                match result.code:
+                    case 301:
+                        text = 'permanently'
+                    case 302:
+                        text = 'with Found'
+                    case 303:
+                        text = 'with See Other'
+                    case 307:
+                        text = 'temporarily'
+                    case 308:
+                        text = 'permanently'
+                    case _:
+                        text = 'with unknown code'
+                linkstat['text'] = text
+                redirection = f'{text} to {result.message}'
+                if self.config.linkcheck_allowed_redirects:
+                    msg = f'redirect  {res_uri} - {redirection}'
+                    logger.warning(msg, location=(result.docname, result.lineno))
+                else:
+                    colour = turquoise if result.code == 307 else purple
+                    msg = colour('redirect  ') + res_uri + colour(f' - {redirection}')
+                    logger.info(msg)
+                self.write_entry(
+                    f'redirected {text}',
+                    result.docname,
+                    filename,
+                    result.lineno,
+                    f'{res_uri} to {result.message}',
                 )
-            self.write_entry(
-                'redirected ' + text,
-                result.docname,
-                filename,
-                result.lineno,
-                result.uri + ' to ' + result.message,
-            )
-        else:
-            raise ValueError('Unknown status %s.' % result.status)
+            case _Status.UNKNOWN:
+                msg = 'Unknown status.'
+                raise ValueError(msg)
 
-    def write_linkstat(self, data: dict[str, str | int]) -> None:
+    def write_linkstat(self, data: dict[str, str | int | _Status]) -> None:
         self.json_outfile.write(json.dumps(data))
         self.json_outfile.write('\n')
 
     def write_entry(
-        self, what: str, docname: str, filename: _StrPath, line: int, uri: str
+        self, what: _Status | str, docname: str, filename: _StrPath, line: int, uri: str
     ) -> None:
         self.txt_outfile.write(f'{filename}:{line}: [{what}] {uri}\n')
 
@@ -246,11 +258,11 @@ class HyperlinkCollector(SphinxPostTransform):
         :param uri: URI to add
         :param node: A node class where the URI was found
         """
-        builder = cast(CheckExternalLinksBuilder, self.app.builder)
+        builder = cast('CheckExternalLinksBuilder', self.app.builder)
         hyperlinks = builder.hyperlinks
         docname = self.env.docname
 
-        if newuri := self.app.emit_firstresult('linkcheck-process-uri', uri):
+        if newuri := self.app.events.emit_firstresult('linkcheck-process-uri', uri):
             uri = newuri
 
         try:
@@ -291,7 +303,12 @@ class HyperlinkAvailabilityChecker:
         for hyperlink in hyperlinks.values():
             if self.is_ignored_uri(hyperlink.uri):
                 yield CheckResult(
-                    hyperlink.uri, hyperlink.docname, hyperlink.lineno, 'ignored', '', 0
+                    uri=hyperlink.uri,
+                    docname=hyperlink.docname,
+                    lineno=hyperlink.lineno,
+                    status=_Status.IGNORED,
+                    message='',
+                    code=0,
                 )
             else:
                 self.wqueue.put(CheckRequest(CHECK_IMMEDIATELY, hyperlink), False)
@@ -330,7 +347,7 @@ class CheckResult(NamedTuple):
     uri: str
     docname: str
     lineno: int
-    status: str
+    status: _Status
     message: str
     code: int
 
@@ -373,16 +390,19 @@ class HyperlinkAvailabilityCheckWorker(Thread):
         self.retries: int = config.linkcheck_retries
         self.rate_limit_timeout = config.linkcheck_rate_limit_timeout
         self._allow_unauthorized = config.linkcheck_allow_unauthorized
+        self._timeout_status: Literal[_Status.BROKEN, _Status.TIMEOUT]
         if config.linkcheck_report_timeouts_as_broken:
-            self._timeout_status = 'broken'
+            self._timeout_status = _Status.BROKEN
         else:
-            self._timeout_status = 'timeout'
+            self._timeout_status = _Status.TIMEOUT
 
         self.user_agent = config.user_agent
         self.tls_verify = config.tls_verify
         self.tls_cacerts = config.tls_cacerts
 
-        self._session = requests._Session()
+        self._session = requests._Session(
+            _ignored_redirects=tuple(map(re.compile, config.linkcheck_ignore))
+        )
 
         super().__init__(daemon=True)
 
@@ -413,17 +433,15 @@ class HyperlinkAvailabilityCheckWorker(Thread):
                 self.wqueue.task_done()
                 continue
             status, info, code = self._check(docname, uri, hyperlink)
-            if status == 'rate-limited':
+            if status == _Status.RATE_LIMITED:
                 logger.info(
-                    darkgray('-rate limited-   ') + uri + darkgray(' | sleeping...')
+                    darkgray('-rate limited-   ') + uri + darkgray(' | sleeping...')  # NoQA: G003
                 )
             else:
                 self.rqueue.put(CheckResult(uri, docname, lineno, status, info, code))
             self.wqueue.task_done()
 
-    def _check(
-        self, docname: str, uri: str, hyperlink: Hyperlink
-    ) -> tuple[str, str, int]:
+    def _check(self, docname: str, uri: str, hyperlink: Hyperlink) -> _URIProperties:
         # check for various conditions without bothering the network
 
         for doc_matcher in self.documents_exclude:
@@ -432,25 +450,25 @@ class HyperlinkAvailabilityCheckWorker(Thread):
                     f'{docname} matched {doc_matcher.pattern} from '
                     'linkcheck_exclude_documents'
                 )
-                return 'ignored', info, 0
+                return _Status.IGNORED, info, 0
 
         if len(uri) == 0 or uri.startswith(('#', 'mailto:', 'tel:')):
-            return 'unchecked', '', 0
+            return _Status.UNCHECKED, '', 0
         if not uri.startswith(('http:', 'https:')):
             if uri_re.match(uri):
                 # Non-supported URI schemes (ex. ftp)
-                return 'unchecked', '', 0
+                return _Status.UNCHECKED, '', 0
 
-            src_dir = path.dirname(hyperlink.docpath)
-            if path.exists(path.join(src_dir, uri)):
-                return 'working', '', 0
-            return 'broken', '', 0
+            if (hyperlink.docpath.parent / uri).exists():
+                return _Status.WORKING, '', 0
+            return _Status.BROKEN, '', 0
 
         # need to actually check the URI
-        status, info, code = '', '', 0
+        status: _Status
+        status, info, code = _Status.UNKNOWN, '', 0
         for _ in range(self.retries):
             status, info, code = self._check_uri(uri, hyperlink)
-            if status != 'broken':
+            if status != _Status.BROKEN:
                 break
 
         return status, info, code
@@ -464,7 +482,7 @@ class HyperlinkAvailabilityCheckWorker(Thread):
             yield self._session.head, {'allow_redirects': True}
         yield self._session.get, {'stream': True}
 
-    def _check_uri(self, uri: str, hyperlink: Hyperlink) -> tuple[str, str, int]:
+    def _check_uri(self, uri: str, hyperlink: Hyperlink) -> _URIProperties:
         req_url, delimiter, anchor = uri.partition('#')
         if delimiter and anchor:
             for rex in self.anchors_ignore:
@@ -519,10 +537,14 @@ class HyperlinkAvailabilityCheckWorker(Thread):
                         try:
                             found = contains_anchor(response, anchor)
                         except UnicodeDecodeError:
-                            return 'ignored', 'unable to decode response content', 0
+                            return (
+                                _Status.IGNORED,
+                                'unable to decode response content',
+                                0,
+                            )
                         if not found:
                             return (
-                                'broken',
+                                _Status.BROKEN,
                                 __("Anchor '%s' not found") % quote(anchor),
                                 0,
                             )
@@ -531,7 +553,7 @@ class HyperlinkAvailabilityCheckWorker(Thread):
                 status_code = response.status_code
                 redirect_status_code = (
                     response.history[-1].status_code if response.history else None
-                )  # NoQA: E501
+                )
                 retry_after = response.headers.get('Retry-After', '')
                 response_url = f'{response.url}'
                 response.raise_for_status()
@@ -543,7 +565,7 @@ class HyperlinkAvailabilityCheckWorker(Thread):
 
             except SSLError as err:
                 # SSL failure; report that the link is broken.
-                return 'broken', str(err), 0
+                return _Status.BROKEN, str(err), 0
 
             except (ConnectionError, TooManyRedirects) as err:
                 # Servers drop the connection on HEAD requests, causing
@@ -551,24 +573,34 @@ class HyperlinkAvailabilityCheckWorker(Thread):
                 error_message = str(err)
                 continue
 
+            except requests._IgnoredRedirection as err:
+                # A redirection to an ignored URI was attempted; report it appropriately
+                return (
+                    _Status.IGNORED,
+                    f'ignored redirect: {err.destination}',
+                    err.status_code,
+                )
+
             except HTTPError as err:
                 error_message = str(err)
 
                 # Unauthorized: the client did not provide required credentials
                 if status_code == 401:
-                    status = 'working' if self._allow_unauthorized else 'broken'
-                    return status, 'unauthorized', 0
+                    if self._allow_unauthorized:
+                        return _Status.WORKING, 'unauthorized', 0
+                    else:
+                        return _Status.BROKEN, 'unauthorized', 0
 
                 # Rate limiting; back-off if allowed, or report failure otherwise
                 if status_code == 429:
                     if next_check := self.limit_rate(response_url, retry_after):
                         self.wqueue.put(CheckRequest(next_check, hyperlink), False)
-                        return 'rate-limited', '', 0
-                    return 'broken', error_message, 0
+                        return _Status.RATE_LIMITED, '', 0
+                    return _Status.BROKEN, error_message, 0
 
                 # Don't claim success/failure during server-side outages
                 if status_code == 503:
-                    return 'ignored', 'service unavailable', 0
+                    return _Status.IGNORED, 'service unavailable', 0
 
                 # For most HTTP failures, continue attempting alternate retrieval methods
                 continue
@@ -576,12 +608,12 @@ class HyperlinkAvailabilityCheckWorker(Thread):
             except Exception as err:
                 # Unhandled exception (intermittent or permanent); report that
                 # the link is broken.
-                return 'broken', str(err), 0
+                return _Status.BROKEN, str(err), 0
 
         else:
             # All available retrieval methods have been exhausted; report
             # that the link is broken.
-            return 'broken', error_message, 0
+            return _Status.BROKEN, error_message, 0
 
         # Success; clear rate limits for the origin
         netloc = urlsplit(req_url).netloc
@@ -591,11 +623,11 @@ class HyperlinkAvailabilityCheckWorker(Thread):
             (response_url.rstrip('/') == req_url.rstrip('/'))
             or _allowed_redirect(req_url, response_url, self.allowed_redirects)
         ):  # fmt: skip
-            return 'working', '', 0
+            return _Status.WORKING, '', 0
         elif redirect_status_code is not None:
-            return 'redirected', response_url, redirect_status_code
+            return _Status.REDIRECTED, response_url, redirect_status_code
         else:
-            return 'redirected', response_url, 0
+            return _Status.REDIRECTED, response_url, 0
 
     def limit_rate(self, response_url: str, retry_after: str | None) -> float | None:
         delay = DEFAULT_DELAY
@@ -681,7 +713,7 @@ class AnchorCheckParser(HTMLParser):
 
     def handle_starttag(self, tag: Any, attrs: Any) -> None:
         for key, value in attrs:
-            if key in ('id', 'name') and value == self.search_anchor:
+            if key in {'id', 'name'} and value == self.search_anchor:
                 self.found = True
                 break
 
@@ -736,29 +768,41 @@ def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_builder(CheckExternalLinksBuilder)
     app.add_post_transform(HyperlinkCollector)
 
-    app.add_config_value('linkcheck_ignore', [], '')
-    app.add_config_value('linkcheck_exclude_documents', [], '')
-    app.add_config_value('linkcheck_allowed_redirects', {}, '')
-    app.add_config_value('linkcheck_auth', [], '')
-    app.add_config_value('linkcheck_request_headers', {}, '')
-    app.add_config_value('linkcheck_retries', 1, '')
-    app.add_config_value('linkcheck_timeout', 30, '', (int, float))
-    app.add_config_value('linkcheck_workers', 5, '')
-    app.add_config_value('linkcheck_anchors', True, '')
+    app.add_config_value('linkcheck_ignore', [], '', types=frozenset({list, tuple}))
+    app.add_config_value(
+        'linkcheck_exclude_documents', [], '', types=frozenset({list, tuple})
+    )
+    app.add_config_value('linkcheck_allowed_redirects', {}, '', types=frozenset({dict}))
+    app.add_config_value('linkcheck_auth', [], '', types=frozenset({list, tuple}))
+    app.add_config_value('linkcheck_request_headers', {}, '', types=frozenset({dict}))
+    app.add_config_value('linkcheck_retries', 1, '', types=frozenset({int}))
+    app.add_config_value('linkcheck_timeout', 30, '', types=frozenset({float, int}))
+    app.add_config_value('linkcheck_workers', 5, '', types=frozenset({int}))
+    app.add_config_value('linkcheck_anchors', True, '', types=frozenset({bool}))
     # Anchors starting with ! are ignored since they are
     # commonly used for dynamic pages
-    app.add_config_value('linkcheck_anchors_ignore', ['^!'], '')
-    app.add_config_value('linkcheck_anchors_ignore_for_url', (), '', (tuple, list))
-    app.add_config_value('linkcheck_rate_limit_timeout', 300.0, '', (int, float))
-    app.add_config_value('linkcheck_allow_unauthorized', False, '')
-    app.add_config_value('linkcheck_report_timeouts_as_broken', False, '', bool)
+    app.add_config_value(
+        'linkcheck_anchors_ignore', ['^!'], '', types=frozenset({list, tuple})
+    )
+    app.add_config_value(
+        'linkcheck_anchors_ignore_for_url', (), '', types=frozenset({list, tuple})
+    )
+    app.add_config_value(
+        'linkcheck_rate_limit_timeout', 300.0, '', types=frozenset({float, int})
+    )
+    app.add_config_value(
+        'linkcheck_allow_unauthorized', False, '', types=frozenset({bool})
+    )
+    app.add_config_value(
+        'linkcheck_report_timeouts_as_broken', False, '', types=frozenset({bool})
+    )
 
     app.add_event('linkcheck-process-uri')
 
     app.connect('config-inited', compile_linkcheck_allowed_redirects, priority=800)
 
     # FIXME: Disable URL rewrite handler for github.com temporarily.
-    # ref: https://github.com/sphinx-doc/sphinx/issues/9435
+    # See: https://github.com/sphinx-doc/sphinx/issues/9435
     # app.connect('linkcheck-process-uri', rewrite_github_anchor)
 
     return {

sphinx/builders/manpage.py

@@ -3,17 +3,16 @@
 from __future__ import annotations
 
 import warnings
-from os import path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from docutils.frontend import OptionParser
 from docutils.io import FileOutput
 
 from sphinx import addnodes
+from sphinx._cli.util.colour import darkgreen
 from sphinx.builders import Builder
 from sphinx.locale import __
 from sphinx.util import logging
-from sphinx.util.console import darkgreen
 from sphinx.util.display import progress_message
 from sphinx.util.nodes import inline_all_toctrees
 from sphinx.util.osutil import ensuredir, make_filename_from_project
@@ -21,6 +20,7 @@ from sphinx.writers.manpage import ManualPageTranslator, ManualPageWriter
 
 if TYPE_CHECKING:
     from collections.abc import Set
+    from typing import Any
 
     from sphinx.application import Sphinx
     from sphinx.config import Config
@@ -30,9 +30,7 @@ logger = logging.getLogger(__name__)
 
 
 class ManualPageBuilder(Builder):
-    """
-    Builds groff output in manual page format.
-    """
+    """Builds groff output in manual page format."""
 
     name = 'man'
     format = 'man'
@@ -44,10 +42,7 @@ class ManualPageBuilder(Builder):
     def init(self) -> None:
         if not self.config.man_pages:
             logger.warning(
-                __(
-                    'no "man_pages" config value found; no manual pages '
-                    'will be written'
-                )
+                __('no "man_pages" config value found; no manual pages will be written')
             )
 
     def get_outdated_docs(self) -> str | list[str]:
@@ -73,7 +68,7 @@ class ManualPageBuilder(Builder):
             docname, name, description, authors, section = info
             if docname not in self.env.all_docs:
                 logger.warning(
-                    __('"man_pages" config value references unknown ' 'document %s'),
+                    __('"man_pages" config value references unknown document %s'),
                     docname,
                 )
                 continue
@@ -90,14 +85,15 @@ class ManualPageBuilder(Builder):
 
             if self.config.man_make_section_directory:
                 dirname = 'man%s' % section
-                ensuredir(path.join(self.outdir, dirname))
+                ensuredir(self.outdir / dirname)
                 targetname = f'{dirname}/{name}.{section}'
             else:
                 targetname = f'{name}.{section}'
 
-            logger.info(darkgreen(targetname) + ' { ')
+            logger.info('%s { ', darkgreen(targetname))
             destination = FileOutput(
-                destination_path=path.join(self.outdir, targetname), encoding='utf-8'
+                destination_path=self.outdir / targetname,
+                encoding='utf-8',
             )
 
             tree = self.env.get_doctree(docname)
@@ -135,9 +131,13 @@ def default_man_pages(config: Config) -> list[tuple[str, str, str, list[str], in
 def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_builder(ManualPageBuilder)
 
-    app.add_config_value('man_pages', default_man_pages, '')
-    app.add_config_value('man_show_urls', False, '')
-    app.add_config_value('man_make_section_directory', False, '')
+    app.add_config_value(
+        'man_pages', default_man_pages, '', types=frozenset({list, tuple})
+    )
+    app.add_config_value('man_show_urls', False, '', types=frozenset({bool}))
+    app.add_config_value(
+        'man_make_section_directory', False, '', types=frozenset({bool})
+    )
 
     return {
         'version': 'builtin',