1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
:mod:`sphinx.ext.duration` -- Measure durations of Sphinx processing
====================================================================
.. module:: sphinx.ext.duration
:synopsis: Measure durations of Sphinx processing
.. versionadded:: 2.4
This extension measures durations of Sphinx processing when reading
documents and is useful for inspecting what document is slowly built.
Durations are printed to console at the end of the build and saved
to a JSON file in the output directory by default.
Enable this extension by adding ``'sphinx.ext.duration'`` to
the :confval:`extensions` list in your :file:`conf.py`:
.. code-block:: python
extensions = [
...
'sphinx.ext.duration',
]
Configuration
-------------
.. confval:: duration_print_total
:type: :code-py:`bool`
:default: :code-py:`True`
Show the total reading duration in the build summary, e.g.:
.. code-block:: text
====================== total reading duration ==========================
Total time reading 31 files: 0m 3.142s
.. versionadded:: 9.0
.. confval:: duration_print_slowest
:type: :code-py:`bool`
:default: :code-py:`True`
Show the slowest durations in the build summary.
The durations are sorted in order from slowest to fastest.
This prints up to :confval:`duration_n_slowest` durations, e.g.:
.. code-block:: text
====================== slowest 5 reading durations =======================
0.012s spam
0.011s ham
0.011s eggs
0.006s lobster
0.005s beans
.. versionadded:: 9.0
.. confval:: duration_n_slowest
:type: :code-py:`int`
:default: :code-py:`5`
Maximum number of slowest durations to show in the build summary
when :confval:`duration_print_slowest` is enabled.
By default, only the ``5`` slowest durations are shown.
Set this to ``0`` to show all durations.
.. versionadded:: 9.0
.. confval:: duration_write_json
:type: :code-py:`str | None`
:default: :code-py:`'sphinx-reading-durations.json'`
Write all reading durations to a JSON file in the output directory
The file contents are a map of the document names to reading durations,
where document names are strings and durations are floats in seconds.
Set this value to an empty string or ``None`` to disable writing the file,
or set it to a relative path to customize it.
This may be useful for testing and setting a limit on reading times.
.. versionadded:: 9.0
.. confval:: duration_limit
:type: :code-py:`float | int | None`
:default: :code-py:`None`
Set a duration limit (in seconds) for reading a document.
If any duration exceeds this value, a warning is emitted.
.. versionadded:: 9.0
|
