Add `_get_settings()` helper function (#13672)

sphinx/__init__.py

@@ -5,22 +5,12 @@
 
 from __future__ import annotations
 
-import warnings
-
 from sphinx.util._pathlib import _StrPath
 
 TYPE_CHECKING = False
 if TYPE_CHECKING:
     from typing import Final
 
-warnings.filterwarnings(
-    'ignore',
-    'The frontend.Option class .*',
-    DeprecationWarning,
-    module='docutils.frontend',
-)
-del warnings
-
 __version__: Final = '8.3.0'
 __display_version__: Final = __version__  # used for command line version
 

sphinx/builders/html/__init__.py

@@ -10,7 +10,6 @@ import posixpath
 import re
 import shutil
 import sys
-import warnings
 from pathlib import Path
 from types import NoneType
 from typing import TYPE_CHECKING
@@ -21,7 +20,6 @@ import docutils.utils
 import jinja2.exceptions
 from docutils import nodes
 from docutils.core import Publisher
-from docutils.frontend import OptionParser
 from docutils.io import DocTreeInput, StringOutput
 
 from sphinx import __display_version__, package_dir
@@ -50,7 +48,7 @@ from sphinx.util._pathlib import _StrPath
 from sphinx.util._timestamps import _format_rfc3339_microseconds
 from sphinx.util._uri import is_url
 from sphinx.util.display import progress_message, status_iterator
-from sphinx.util.docutils import new_document
+from sphinx.util.docutils import _get_settings, new_document
 from sphinx.util.fileutil import copy_asset
 from sphinx.util.i18n import format_date
 from sphinx.util.inventory import InventoryFile
@@ -459,15 +457,9 @@ class StandaloneHTMLBuilder(Builder):
             self.load_indexer(docnames)
 
         self.docwriter = HTMLWriter(self)
-        with warnings.catch_warnings():
-            warnings.filterwarnings('ignore', category=DeprecationWarning)
-            # DeprecationWarning: The frontend.OptionParser class will be replaced
-            # by a subclass of argparse.ArgumentParser in Docutils 0.21 or later.
-            self.docsettings: Any = OptionParser(
-                defaults=self.env.settings,
-                components=(self.docwriter,),
-                read_config_files=True,
-            ).get_default_values()
+        self.docsettings = _get_settings(
+            HTMLWriter, defaults=self.env.settings, read_config_files=True
+        )
         self.docsettings.compact_lists = bool(self.config.html_compact_lists)
 
         # determine the additional indices to include

sphinx/builders/latex/__init__.py

@@ -4,12 +4,9 @@ from __future__ import annotations
 
 import os
 import os.path
-import warnings
 from pathlib import Path
 from typing import TYPE_CHECKING
 
-from docutils.frontend import OptionParser
-
 import sphinx.builders.latex.nodes  # NoQA: F401  # Workaround: import this before writer to avoid ImportError
 from sphinx import addnodes, highlighting, package_dir
 from sphinx._cli.util.colour import darkgreen
@@ -27,7 +24,7 @@ from sphinx.errors import NoUri, SphinxError
 from sphinx.locale import _, __
 from sphinx.util import logging, texescape
 from sphinx.util.display import progress_message, status_iterator
-from sphinx.util.docutils import SphinxFileOutput, new_document
+from sphinx.util.docutils import SphinxFileOutput, _get_settings, new_document
 from sphinx.util.fileutil import copy_asset_file
 from sphinx.util.i18n import format_date
 from sphinx.util.nodes import inline_all_toctrees
@@ -301,15 +298,9 @@ class LaTeXBuilder(Builder):
 
     def write_documents(self, _docnames: Set[str]) -> None:
         docwriter = LaTeXWriter(self)
-        with warnings.catch_warnings():
-            warnings.filterwarnings('ignore', category=DeprecationWarning)
-            # DeprecationWarning: The frontend.OptionParser class will be replaced
-            # by a subclass of argparse.ArgumentParser in Docutils 0.21 or later.
-            docsettings: Any = OptionParser(
-                defaults=self.env.settings,
-                components=(docwriter,),
-                read_config_files=True,
-            ).get_default_values()
+        docsettings = _get_settings(
+            LaTeXWriter, defaults=self.env.settings, read_config_files=True
+        )
 
         for entry in self.document_data:
             docname, targetname, title, author, themename = entry[:5]

sphinx/builders/manpage.py

@@ -2,10 +2,8 @@
 
 from __future__ import annotations
 
-import warnings
 from typing import TYPE_CHECKING
 
-from docutils.frontend import OptionParser
 from docutils.io import FileOutput
 
 from sphinx import addnodes
@@ -14,13 +12,13 @@ from sphinx.builders import Builder
 from sphinx.locale import __
 from sphinx.util import logging
 from sphinx.util.display import progress_message
+from sphinx.util.docutils import _get_settings
 from sphinx.util.nodes import inline_all_toctrees
 from sphinx.util.osutil import ensuredir, make_filename_from_project
 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
@@ -54,15 +52,9 @@ class ManualPageBuilder(Builder):
     @progress_message(__('writing'))
     def write_documents(self, _docnames: Set[str]) -> None:
         docwriter = ManualPageWriter(self)
-        with warnings.catch_warnings():
-            warnings.filterwarnings('ignore', category=DeprecationWarning)
-            # DeprecationWarning: The frontend.OptionParser class will be replaced
-            # by a subclass of argparse.ArgumentParser in Docutils 0.21 or later.
-            docsettings: Any = OptionParser(
-                defaults=self.env.settings,
-                components=(docwriter,),
-                read_config_files=True,
-            ).get_default_values()
+        docsettings = _get_settings(
+            ManualPageWriter, defaults=self.env.settings, read_config_files=True
+        )
 
         for info in self.config.man_pages:
             docname, name, description, authors, section = info

sphinx/builders/texinfo.py

@@ -3,11 +3,9 @@
 from __future__ import annotations
 
 import os.path
-import warnings
 from typing import TYPE_CHECKING
 
 from docutils import nodes
-from docutils.frontend import OptionParser
 from docutils.io import FileOutput
 
 from sphinx import addnodes, package_dir
@@ -18,14 +16,13 @@ from sphinx.errors import NoUri
 from sphinx.locale import _, __
 from sphinx.util import logging
 from sphinx.util.display import progress_message, status_iterator
-from sphinx.util.docutils import new_document
+from sphinx.util.docutils import _get_settings, new_document
 from sphinx.util.nodes import inline_all_toctrees
 from sphinx.util.osutil import SEP, copyfile, ensuredir, make_filename_from_project
 from sphinx.writers.texinfo import TexinfoTranslator, TexinfoWriter
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Set
-    from typing import Any
 
     from docutils.nodes import Node
 
@@ -119,15 +116,9 @@ class TexinfoBuilder(Builder):
             with progress_message(__('writing')):
                 self.post_process_images(doctree)
                 docwriter = TexinfoWriter(self)
-                with warnings.catch_warnings():
-                    warnings.filterwarnings('ignore', category=DeprecationWarning)
-                    # DeprecationWarning: The frontend.OptionParser class will be replaced
-                    # by a subclass of argparse.ArgumentParser in Docutils 0.21 or later.
-                    settings: Any = OptionParser(
-                        defaults=self.env.settings,
-                        components=(docwriter,),
-                        read_config_files=True,
-                    ).get_default_values()
+                settings = _get_settings(
+                    TexinfoWriter, defaults=self.env.settings, read_config_files=True
+                )
                 settings.author = author
                 settings.title = title
                 settings.texinfo_filename = targetname[:-5] + '.info'

sphinx/testing/restructuredtext.py

@@ -1,19 +1,15 @@
 from __future__ import annotations
 
-import warnings
 from typing import TYPE_CHECKING
 
 from docutils import nodes
-from docutils.frontend import OptionParser
 
 from sphinx.io import SphinxBaseReader
 from sphinx.parsers import RSTParser
 from sphinx.transforms import SphinxTransformer
-from sphinx.util.docutils import LoggingReporter, sphinx_domains
+from sphinx.util.docutils import LoggingReporter, _get_settings, sphinx_domains
 
 if TYPE_CHECKING:
-    from docutils.frontend import Values
-
     from sphinx.application import Sphinx
 
 
@@ -33,12 +29,7 @@ def parse(app: Sphinx, text: str, docname: str = 'index') -> nodes.document:
         'output_encoding': 'unicode',
         'traceback': True,
     }
-    with warnings.catch_warnings():
-        warnings.filterwarnings('ignore', category=DeprecationWarning)
-        option_parser = OptionParser(
-            components=(RSTParser, SphinxBaseReader), defaults=settings_overrides
-        )
-    settings: Values = option_parser.get_default_values()  # type: ignore[assignment]
+    settings = _get_settings(SphinxBaseReader, RSTParser, defaults=settings_overrides)
     settings._source = source_path
     settings.env = env
 

sphinx/util/docutils.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import os
 import re
+import warnings
 from contextlib import contextmanager
 from copy import copy
 from pathlib import Path
@@ -11,6 +12,7 @@ from typing import TYPE_CHECKING
 
 import docutils
 from docutils import nodes
+from docutils.frontend import OptionParser
 from docutils.io import FileOutput
 from docutils.parsers.rst import Directive, directives, roles
 from docutils.statemachine import StateMachine
@@ -27,10 +29,11 @@ report_re = re.compile(
 )
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator, Sequence
+    from collections.abc import Iterator, Mapping, Sequence
     from types import ModuleType, TracebackType
     from typing import Any, Protocol
 
+    from docutils import Component
     from docutils.frontend import Values
     from docutils.nodes import Element, Node, system_message
     from docutils.parsers.rst.states import Inliner
@@ -816,3 +819,21 @@ def new_document(source_path: str, settings: Any = None) -> nodes.document:
     document = nodes.document(settings, reporter, source=source_path)
     document.note_source(source_path, -1)
     return document
+
+
+def _get_settings(
+    *components: Component | type[Component],
+    defaults: Mapping[str, Any],
+    read_config_files: bool = False,
+) -> Values:
+    with warnings.catch_warnings(action='ignore', category=DeprecationWarning):
+        # DeprecationWarning: The frontend.OptionParser class will be replaced
+        # by a subclass of argparse.ArgumentParser in Docutils 0.21 or later.
+        # DeprecationWarning: The frontend.Option class will be removed
+        # in Docutils 0.21 or later.
+        option_parser = OptionParser(
+            components=components,
+            defaults=defaults,
+            read_config_files=read_config_files,
+        )
+    return option_parser.get_default_values()  # type: ignore[return-value]

tests/test_markup/test_markup.py

@@ -3,11 +3,10 @@
 from __future__ import annotations
 
 import re
-import warnings
 from types import SimpleNamespace
 
 import pytest
-from docutils import frontend, nodes, utils
+from docutils import nodes, utils
 from docutils.parsers.rst import Parser as RstParser
 
 from sphinx import addnodes
@@ -17,7 +16,7 @@ from sphinx.roles import XRefRole
 from sphinx.testing.util import assert_node
 from sphinx.transforms import SphinxSmartQuotes
 from sphinx.util import texescape
-from sphinx.util.docutils import sphinx_domains
+from sphinx.util.docutils import _get_settings, sphinx_domains
 from sphinx.writers.html import HTMLWriter
 from sphinx.writers.html5 import HTML5Translator
 from sphinx.writers.latex import LaTeXTranslator, LaTeXWriter
@@ -27,15 +26,9 @@ from sphinx.writers.latex import LaTeXTranslator, LaTeXWriter
 def settings(app):
     env = app.env
     texescape.init()  # otherwise done by the latex builder
-    with warnings.catch_warnings():
-        warnings.filterwarnings('ignore', category=DeprecationWarning)
-        # DeprecationWarning: The frontend.OptionParser class will be replaced
-        # by a subclass of argparse.ArgumentParser in Docutils 0.21 or later.
-        optparser = frontend.OptionParser(
-            components=(RstParser, HTMLWriter, LaTeXWriter),
-            defaults=default_settings,
-        )
-    settings = optparser.get_default_values()
+    settings = _get_settings(
+        RstParser, HTMLWriter, LaTeXWriter, defaults=default_settings
+    )
     settings.smart_quotes = True
     settings.env = env
     settings.env.current_document.docname = 'dummy'

tests/test_search.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import json
-import warnings
 from io import BytesIO
 from typing import TYPE_CHECKING
 
@@ -169,12 +168,7 @@ def test_term_in_raw_directive(app: SphinxTestApp) -> None:
 
 
 def test_IndexBuilder():
-    with warnings.catch_warnings():
-        warnings.filterwarnings('ignore', category=DeprecationWarning)
-        # DeprecationWarning: The frontend.OptionParser class will be replaced
-        # by a subclass of argparse.ArgumentParser in Docutils 0.21 or later.
-        optparser = frontend.OptionParser(components=(rst.Parser,))
-    settings = optparser.get_default_values()
+    settings = frontend.get_default_settings(rst.Parser)
     parser = rst.Parser()
 
     domain1 = DummyDomain(

tests/test_util/test_util_nodes.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import warnings
 from textwrap import dedent
 from typing import TYPE_CHECKING, Any
 
@@ -30,11 +29,7 @@ def _transform(doctree) -> None:
 
 
 def create_new_document() -> document:
-    with warnings.catch_warnings():
-        warnings.filterwarnings('ignore', category=DeprecationWarning)
-        # DeprecationWarning: The frontend.OptionParser class will be replaced
-        # by a subclass of argparse.ArgumentParser in Docutils 0.21 or later.
-        settings = frontend.OptionParser(components=(rst.Parser,)).get_default_values()
+    settings = frontend.get_default_settings(rst.Parser)
     settings.id_prefix = 'id'
     document = new_document('dummy.txt', settings)
     return document