Add configuration options to duration extension

CHANGES.rst

@@ -19,6 +19,7 @@ Features added
 * #13439: linkcheck: Permit warning on every redirect with
   ``linkcheck_allowed_redirects = {}``.
   Patch by Adam Turner.
+* Extend duration extension with new configuration options.
 
 Bugs fixed
 ----------

doc/usage/extensions/duration.rst

@@ -7,5 +7,68 @@
 .. versionadded:: 2.4
 
 This extension measures durations of Sphinx processing and show its
-result at end of the build.  It is useful for inspecting what document
-is slowly built.
+result at end of the build. It is useful for inspecting what document
+is slowly built. Enable this extension by adding it to ``conf.py``:
+
+.. code-block:: python
+
+   extensions = ['sphinx.ext.duration']
+
+Optionally, configure the extension by adding ``duration_options`` as a config value.
+In ``conf.py``:
+
+.. code-block:: python
+
+   extensions = ['sphinx.ext.duration']
+
+   # disable printing totals and writing durations
+   # and only show the 10 slowest times
+   duration_options = {
+       'print_total': False,
+       'print_slowest' : True,
+       'n_slowest': 10,
+       'write_durations' : False,
+   }
+
+   def setup(app):
+       app.add_config_value('duration_options', duration_options, 'env')
+
+
+Configuration
+=============
+
+Configure this extension using a ``duration_options`` dictionary.
+
+.. confval:: print_slowest
+   :type: :code-py:`bool`
+   :default: :code-py:`True`
+
+   Show the slowest durations in the build summary.
+
+.. confval:: n_slowest
+   :type: :code-py:`int`
+   :default: :code-py:`5`
+
+   Maximum number of slowest durations to show in the build summary.
+   The durations are sorted in order from slow to fast. Only the ``5`` slowest
+   durations are shown by default. Set this to ``-1`` to show all durations.
+
+   .. versionadded:: 8.3
+
+.. confval:: print_total
+   :type: :code-py:`bool`
+   :default: :code-py:`True`
+
+   Show the total reading duration in the build summary.
+
+   .. versionadded:: 8.3
+
+.. confval:: write_durations
+   :type: :code-py:`bool`
+   :default: :code-py:`True`
+
+   Write all reading durations to a JSON file ``sphinx_reading_durations.json``
+   in the build directory. File paths and durations (in seconds) are saved as
+   keys and values, respectively.
+
+   .. versionadded:: 8.3

sphinx/ext/duration.py

@@ -2,9 +2,12 @@
 
 from __future__ import annotations
 
+import json
 import time
+from datetime import datetime, timedelta, timezone
 from itertools import islice
 from operator import itemgetter
+from pathlib import Path
 from typing import TYPE_CHECKING
 
 import sphinx
@@ -24,6 +27,13 @@ class _DurationDomainData(TypedDict):
         reading_durations: dict[str, float]
 
 
+DEFAULT_OPTIONS = {
+    'print_total': True,
+    'print_slowest': True,
+    'n_slowest': 5,
+    'write_durations': True,
+}
+
 logger = logging.getLogger(__name__)
 
 
@@ -79,18 +89,50 @@ def on_doctree_read(app: Sphinx, doctree: nodes.document) -> None:
 def on_build_finished(app: Sphinx, error: Exception) -> None:
     """Display duration ranking on the current build."""
     domain = app.env.domains['duration']
-    if not domain.reading_durations:
+    reading_durations = domain.reading_durations
+    if not reading_durations:
         return
-    durations = sorted(
-        domain.reading_durations.items(), key=itemgetter(1), reverse=True
-    )
 
-    logger.info('')
-    logger.info(
-        __('====================== slowest reading durations =======================')
-    )
-    for docname, d in islice(durations, 5):
-        logger.info(f'{d:.3f} {docname}')  # NoQA: G004
+    # Get default options and update with user-specified values
+    options = DEFAULT_OPTIONS.copy()
+    user_options = getattr(app.config, 'duration_options', DEFAULT_OPTIONS)
+    options.update(user_options)
+
+    if options['print_total']:
+        logger.info('')
+        logger.info(
+            __(
+                '====================== total reading duration =========================='
+            )
+        )
+
+        n_files = len(reading_durations)
+        s = '' if n_files == 1 else 's'
+
+        total = sum(reading_durations.values())
+        logger.info('Total time reading %d file%s:\n', n_files, s)
+        logger.info(_format_seconds(total, multiline=True))
+
+    if options['print_slowest']:
+        logger.info('')
+        logger.info(
+            __(
+                '====================== slowest reading durations ======================='
+            )
+        )
+        sorted_durations = sorted(
+            reading_durations.items(), key=itemgetter(1), reverse=True
+        )
+        n_slowest = options['n_slowest']
+        n_slowest = len(sorted_durations) if n_slowest == -1 else n_slowest
+        for docname, d in islice(sorted_durations, n_slowest):
+            logger.info('%s %s', _format_seconds(d), docname)
+
+    if options['write_durations']:
+        # Write to JSON
+        out_file = Path(app.builder.outdir) / 'sphinx_durations.json'
+        with out_file.open('w', encoding='utf-8') as fid:
+            json.dump(reading_durations, fid, indent=4)  # indent makes it more readable
 
 
 def setup(app: Sphinx) -> dict[str, bool | str]:
@@ -105,3 +147,19 @@ def setup(app: Sphinx) -> dict[str, bool | str]:
         'parallel_read_safe': True,
         'parallel_write_safe': True,
     }
+
+
+def _format_seconds(seconds: float, multiline: bool = False) -> str:
+    """Convert seconds to a formatted string."""
+    dt = datetime(1, 1, 1, tzinfo=timezone.utc) + timedelta(seconds=seconds)  # noqa: UP017
+    minutes = dt.hour * 60 + dt.minute
+    seconds = dt.second
+    milliseconds = round(dt.microsecond / 1000.0)
+    if multiline:
+        return (
+            f'minutes:      {minutes:>3}\n'
+            f'seconds:      {seconds:>3}\n'
+            f'milliseconds: {milliseconds:>3}'
+        )
+    else:
+        return f'{minutes:02d}:{seconds:02d}.{milliseconds:03d}'

tests/test_extensions/test_ext_duration.py

@@ -2,7 +2,10 @@
 
 from __future__ import annotations
 
+import json
+import os
 import re
+from pathlib import Path
 from typing import TYPE_CHECKING
 
 import pytest
@@ -16,8 +19,92 @@
     testroot='basic',
     confoverrides={'extensions': ['sphinx.ext.duration']},
 )
-def test_githubpages(app: SphinxTestApp) -> None:
+def test_duration(app: SphinxTestApp) -> None:
     app.build()
 
     assert 'slowest reading durations' in app.status.getvalue()
     assert re.search('\\d+\\.\\d{3} index\n', app.status.getvalue())
+
+    assert 'total reading duration' in app.status.getvalue()
+    assert 'Total time reading 1 file:' in app.status.getvalue()
+    assert re.search(
+        r'minutes:\s*\d+\s*seconds:\s*\d+\s*milliseconds:\s*\d+', app.status.getvalue()
+    )
+
+    fname = 'sphinx_durations.json'
+    assert fname in os.listdir(app.outdir)  # noqa: PTH208
+    with (Path(app.outdir) / fname).open() as f:
+        data = json.load(f)
+
+    keys = list(data.keys())
+    values = list(data.values())
+    assert keys == ['index']
+    assert len(values) == 1
+    assert isinstance(values[0], float)
+
+
+@pytest.mark.sphinx(
+    'dummy',
+    testroot='intl',
+    confoverrides={'extensions': ['sphinx.ext.duration']},
+)
+def test_n_slowest_value(app: SphinxTestApp) -> None:
+    options = {'n_slowest': 0}
+    app.add_config_value('duration_options', options, 'env')
+    app.build()
+
+    assert 'slowest reading durations' in app.status.getvalue()
+    assert re.search('\\d+\\.\\d{3} index\n', app.status.getvalue()) is None
+
+
+@pytest.mark.sphinx(
+    'dummy',
+    testroot='root',
+    confoverrides={'extensions': ['sphinx.ext.duration']},
+)
+def test_n_slowest_all(app: SphinxTestApp) -> None:
+    options = {'n_slowest': -1}
+    app.add_config_value('duration_options', options, 'env')
+    app.build()
+
+    assert 'slowest reading durations' in app.status.getvalue()
+    assert re.search('\\d+\\.\\d{3} index\n', app.status.getvalue())
+
+
+@pytest.mark.sphinx(
+    'dummy',
+    testroot='basic',
+    confoverrides={'extensions': ['sphinx.ext.duration']},
+)
+def test_print_slowest_false(app: SphinxTestApp) -> None:
+    options = {'print_slowest': False}
+    app.add_config_value('duration_options', options, 'env')
+    app.build()
+
+    assert 'slowest reading durations' not in app.status.getvalue()
+
+
+@pytest.mark.sphinx(
+    'dummy',
+    testroot='basic',
+    confoverrides={'extensions': ['sphinx.ext.duration']},
+)
+def test_print_total_false(app: SphinxTestApp) -> None:
+    options = {'print_total': False}
+    app.add_config_value('duration_options', options, 'env')
+    app.build()
+
+    assert 'total reading duration' not in app.status.getvalue()
+
+
+@pytest.mark.sphinx(
+    'dummy',
+    testroot='search',
+    confoverrides={'extensions': ['sphinx.ext.duration']},
+)
+def test_write_durations_false(app: SphinxTestApp) -> None:
+    options = {'write_durations': False}
+    app.add_config_value('duration_options', options, 'env')
+    app.build()
+
+    assert 'sphinx_durations.json' not in os.listdir(app.outdir)  # noqa: PTH208