CLI

sphinx-performance

sphinx-performance is used via its command line interface.

To get a first help, type sphinx-performance --help

$ sphinx-performance --help
Usage: sphinx-performance [OPTIONS]

  CLI performance handling

Options:
  --project TEXT      Defines the project to build
  --profile TEXT      Activates profiling for given area
  --parallel INTEGER  Number of parallel processes to use. Same as -j for
                      sphinx-build
  --builder TEXT      Define the builder to use
  --keep              Keeps the temporary src and build folders
  --browser           Opens the project in your browser
  --snakeviz          Opens snakeviz view for measured profiles in browser
  --debug             console.prints more information, incl. sphinx build
                      output
  --temp TEXT         Base folder path to use for temp folders. Must exist.
  --csv TEXT          CSV file path, which shall store the results.
  --help              Show this message and exit.

Use sphinx-command to compare different Sphinx project setups.

For deeper analysis, use sphinx-analysis.

--project

--project allows to select a specific test project.

This can be an integrated project or a path to a self defined project:

sphinx-performance --project needs
sphinx-performance --project my/sphinx/project

Can be used multiple times, so that for each project a specific test run gets executed:

sphinx-performance --project basic --project needs

Default: basic

--parallel

Defines the amount of cores (Sphinx workers) to use for the build.

Uses internally the Sphinx option -j.

Parallel execution can bring huge benefits, if the documentation is based on multiple pages.

$ sphinx-performance --parallel 1 --parallel 4 --pages 30

Running 2 test configurations.


Running 2 test configurations.

─────────────────────────────────── Run 1/2 ────────────────────────────────────
Project:         basic
Core/s:          1
Builder:         html
Config:          pages: 30, sphinx: 5.1, dummies: 10, folders: 0, depth: 1
Info:            #dummies: 300, #pages: 30, #indexes: 1, #folders: 0

Docs path:       /tmp/tmp8grmfqi8
Docs files:      31 rst files with 26.57 kB
Docs setup:      0.07 s

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.
sphinx-rtd-theme 1.0.0 requires docutils<0.18, but you have docutils 0.19 which is incompatible.
Deps setup:      2.00 s

Build files:     116 files with 1198.75 kB
File max️:        281.82 kB by /tmp/tmp8grmfqi8/_build/_static/jquery-3.6.0.js
File min:        0.01 kB by /tmp/tmp8grmfqi8/_build/_static/README
File Ø:          10.33 kB (0.01 s)
Reading time:    0.51 s
Writing time:    0.53 s
Build Duration:  1.73 s
─────────────────────────────────── Run 2/2 ────────────────────────────────────
Project:         basic
Core/s:          4
Builder:         html
Config:          pages: 30, sphinx: 5.1, dummies: 10, folders: 0, depth: 1
Info:            #dummies: 300, #pages: 30, #indexes: 1, #folders: 0

Docs path:       /tmp/tmpvo7vrb8u
Docs files:      31 rst files with 26.57 kB
Docs setup:      0.07 s

Deps setup:      0.73 s

Build files:     116 files with 1199.60 kB
File max️:        281.82 kB by /tmp/tmpvo7vrb8u/_build/_static/jquery-3.6.0.js
File min:        0.01 kB by /tmp/tmpvo7vrb8u/_build/_static/README
File Ø:          10.34 kB (0.02 s)
Reading time:    0.11 s
Writing time:    0.12 s
Build Duration:  1.85 s
─────────────────────────────────── RESULTS ────────────────────────────────────
╭───────────────┬────────────┬────────────╮
│       #       │   Run 1    │   Run 2    │
├───────────────┼────────────┼────────────┤
│    runtime    │    1.73    │    1.85    │
│    project    │   basic    │   basic    │
│               │            │            │
│    builder    │    html    │    html    │
│    dummies    │     10     │     10     │
│    sphinx     │    5.1     │    5.1     │
│     pages     │     30     │     30     │
│     depth     │     1      │     1      │
│   parallel    │     1      │     4      │
│    folders    │     0      │     0      │
│               │            │            │
│   #folders    │     0      │     0      │
│   #dummies    │    300     │    300     │
│    #pages     │     30     │     30     │
│   #indexes    │     1      │     1      │
│               │            │            │
│ avg file size │  10.33 kB  │  10.34 kB  │
│  folder size  │ 1198.75 kB │ 1199.60 kB │
│ writing time  │   0.53 s   │   0.12 s   │
│    # files    │    116     │    116     │
│ avg file time │   0.01 s   │   0.02 s   │
│ reading time  │   0.51 s   │   0.11 s   │
│ min file size │  0.01 kB   │  0.01 kB   │
│ max file size │ 281.82 kB  │ 281.82 kB  │
│               │            │            │
╰───────────────┴────────────┴────────────╯

Overall runtime: 3.58 seconds.

--builder

Defines the builder to use, for instance html, text, json, xml.

Type make in a sphinx project folder so see all available builders.

Can be used multiple times, so that for each builder a specific test run gets executed.

$ sphinx-performance --pages 2 --builder html --builder text

Running 2 test configurations.


Running 2 test configurations.

─────────────────────────────────── Run 1/2 ────────────────────────────────────
Project:         basic
Core/s:          1
Builder:         html
Config:          pages: 2, sphinx: 5.1, dummies: 10, folders: 0, depth: 1
Info:            #dummies: 20, #pages: 2, #indexes: 1, #folders: 0

Docs path:       /tmp/tmp0n5x7rwe
Docs files:      3 rst files with 1.93 kB
Docs setup:      0.02 s

Deps setup:      0.73 s

Build files:     32 files with 586.37 kB
File max️:        281.82 kB by /tmp/tmp0n5x7rwe/_build/_static/jquery-3.6.0.js
File min:        0.01 kB by /tmp/tmp0n5x7rwe/_build/_static/README
File Ø:          18.32 kB (0.02 s)
Reading time:    0.02 s
Writing time:    0.08 s
Build Duration:  0.74 s
─────────────────────────────────── Run 2/2 ────────────────────────────────────
Project:         basic
Core/s:          1
Builder:         text
Config:          pages: 2, sphinx: 5.1, dummies: 10, folders: 0, depth: 1
Info:            #dummies: 20, #pages: 2, #indexes: 1, #folders: 0

Docs path:       /tmp/tmp56_1phfo
Docs files:      3 rst files with 1.93 kB
Docs setup:      0.02 s

Deps setup:      0.73 s

Build files:     7 files with 41.92 kB
File max️:        14.44 kB by 
/tmp/tmp56_1phfo/_build/.doctrees/environment.pickle
File min:        0.32 kB by /tmp/tmp56_1phfo/_build/index.txt
File Ø:          5.99 kB (0.08 s)
Reading time:    0.01 s
Writing time:    0.01 s
Build Duration:  0.55 s
─────────────────────────────────── RESULTS ────────────────────────────────────
╭───────────────┬───────────┬──────────╮
│       #       │   Run 1   │  Run 2   │
├───────────────┼───────────┼──────────┤
│    runtime    │   0.74    │   0.55   │
│    project    │   basic   │  basic   │
│               │           │          │
│     pages     │     2     │    2     │
│   parallel    │     1     │    1     │
│    folders    │     0     │    0     │
│    builder    │   html    │   text   │
│     depth     │     1     │    1     │
│    sphinx     │    5.1    │   5.1    │
│    dummies    │    10     │    10    │
│               │           │          │
│   #indexes    │     1     │    1     │
│   #dummies    │    20     │    20    │
│    #pages     │     2     │    2     │
│   #folders    │     0     │    0     │
│               │           │          │
│  folder size  │ 586.37 kB │ 41.92 kB │
│ reading time  │  0.02 s   │  0.01 s  │
│ avg file size │ 18.32 kB  │ 5.99 kB  │
│ min file size │  0.01 kB  │ 0.32 kB  │
│ writing time  │  0.08 s   │  0.01 s  │
│ avg file time │  0.02 s   │  0.08 s  │
│    # files    │    32     │    7     │
│ max file size │ 281.82 kB │ 14.44 kB │
│               │           │          │
╰───────────────┴───────────┴──────────╯

Overall runtime: 1.29 seconds.

Project parameters

sphinx-performance takes every project parameters and provides it to the test project.

Which parameters are need and how their defaults looks like are documented in the test project specific documentation.

$ sphinx-performance --pages 2 --dummies 5

Running 1 test configurations.


Running 1 test configurations.

─────────────────────────────────── Run 1/1 ────────────────────────────────────
Project:         basic
Core/s:          1
Builder:         html
Config:          pages: 2, dummies: 5, sphinx: 5.1, folders: 0, depth: 1
Info:            #dummies: 10, #pages: 2, #indexes: 1, #folders: 0

Docs path:       /tmp/tmpbawulczh
Docs files:      3 rst files with 1.14 kB
Docs setup:      0.02 s

Deps setup:      0.76 s

Build files:     32 files with 575.93 kB
File max️:        281.82 kB by /tmp/tmpbawulczh/_build/_static/jquery-3.6.0.js
File min:        0.01 kB by /tmp/tmpbawulczh/_build/_static/README
File Ø:          18.00 kB (0.02 s)
Reading time:    0.01 s
Writing time:    0.07 s
Build Duration:  0.70 s
─────────────────────────────────── RESULTS ────────────────────────────────────
╭───────────────┬───────────╮
│       #       │   Run 1   │
├───────────────┼───────────┤
│    runtime    │   0.70    │
│    project    │   basic   │
│               │           │
│    folders    │     0     │
│    builder    │   html    │
│   parallel    │     1     │
│    sphinx     │    5.1    │
│     depth     │     1     │
│     pages     │     2     │
│    dummies    │     5     │
│               │           │
│   #folders    │     0     │
│   #dummies    │    10     │
│   #indexes    │     1     │
│    #pages     │     2     │
│               │           │
│ writing time  │  0.07 s   │
│  folder size  │ 575.93 kB │
│ avg file time │  0.02 s   │
│ max file size │ 281.82 kB │
│ min file size │  0.01 kB  │
│    # files    │    32     │
│ reading time  │  0.01 s   │
│ avg file size │ 18.00 kB  │
│               │           │
╰───────────────┴───────────╯

Overall runtime: 0.70 seconds.

Commonly used parameters

This is a list of parameters, which are supported by most test projects.

--pages

Amount of pages per folder:

sphinx-performance --pages 20

--folders

Amount of folders per folder depth:

sphinx-performance --folders 10 --pages 10

This will create 10 sub-folders, each containing 10 pages.

--depth

Folder depth.

1 = Create folders once on root level

2 = Create also folder again in folders of root level

And so one.

This means the amount of folders and files raises exponential:

sphinx-performance --pages 10 --folders 10 --depth 0  # 10 pages, 0 folders
sphinx-performance --pages 10 --folders 10 --depth 1  # 110 pages, 10 folders
sphinx-performance --pages 10 --folders 10 --depth 2  # 1110 pages, 100 folders

--ref

Allows to select a preconfigured testproject setup by its reference name.

Each test project can provide its own set of configurations.

There is no common naming rule, how such references shall be named in Sphinx-Performance. For details take a look at the variable references of performance.py file of each test project. For embedded projects:

• Basic config file

• Needs config file

• Theme config file

Example:

sphinx-performance --project theme --ref alabaster --ref rtd --ref pydata --ref furo --browser --depth 2

Config parameters set by a reference configuration can be easily overwritten by just using the parameter in the command line call:

sphinx-performance --ref small --folders 50

Parameter matrix

All project parameters can be set multiple times, so that tests gets executed for each given parameter.

sphinx-performance creates also a configuration matrix, if multiple parameters are given multiple times.

This --pages 1 --pages 5 --dummies 1 --dummies 20 would run 4 tests with:

1. pages = 1 and dummies = 1

2. pages = 1 and dummies = 20

3. pages = 5 and dummies = 1

4. pages = 5 and dummies = 20

$ sphinx-performance --pages 1 --pages 5 --dummies 1 --dummies 20

Running 4 test configurations.


Running 4 test configurations.

─────────────────────────────────── Run 1/4 ────────────────────────────────────
Project:         basic
Core/s:          1
Builder:         html
Config:          pages: 1, dummies: 1, sphinx: 5.1, folders: 0, depth: 1
Info:            #dummies: 1, #pages: 1, #indexes: 1, #folders: 0

Docs path:       /tmp/tmpkrn7v4my
Docs files:      2 rst files with 0.34 kB
Docs setup:      0.02 s

Deps setup:      0.73 s

Build files:     29 files with 557.60 kB
File max️:        281.82 kB by /tmp/tmpkrn7v4my/_build/_static/jquery-3.6.0.js
File min:        0.01 kB by /tmp/tmpkrn7v4my/_build/_static/README
File Ø:          19.23 kB (0.02 s)
Reading time:    0.01 s
Writing time:    0.05 s
Build Duration:  0.69 s
─────────────────────────────────── Run 2/4 ────────────────────────────────────
Project:         basic
Core/s:          1
Builder:         html
Config:          pages: 1, dummies: 20, sphinx: 5.1, folders: 0, depth: 1
Info:            #dummies: 20, #pages: 1, #indexes: 1, #folders: 0

Docs path:       /tmp/tmpjkoo4tgu
Docs files:      2 rst files with 1.88 kB
Docs setup:      0.02 s

Deps setup:      0.74 s

Build files:     29 files with 577.60 kB
File max️:        281.82 kB by /tmp/tmpjkoo4tgu/_build/_static/jquery-3.6.0.js
File min:        0.01 kB by /tmp/tmpjkoo4tgu/_build/_static/README
File Ø:          19.92 kB (0.02 s)
Reading time:    0.01 s
Writing time:    0.06 s
Build Duration:  0.72 s
─────────────────────────────────── Run 3/4 ────────────────────────────────────
Project:         basic
Core/s:          1
Builder:         html
Config:          pages: 5, dummies: 1, sphinx: 5.1, folders: 0, depth: 1
Info:            #dummies: 5, #pages: 5, #indexes: 1, #folders: 0

Docs path:       /tmp/tmpo73jgcyi
Docs files:      6 rst files with 1.00 kB
Docs setup:      0.02 s

Deps setup:      0.72 s

Build files:     41 files with 598.35 kB
File max️:        281.82 kB by /tmp/tmpo73jgcyi/_build/_static/jquery-3.6.0.js
File min:        0.01 kB by /tmp/tmpo73jgcyi/_build/_static/README
File Ø:          14.59 kB (0.02 s)
Reading time:    0.03 s
Writing time:    0.08 s
Build Duration:  0.73 s
─────────────────────────────────── Run 4/4 ────────────────────────────────────
Project:         basic
Core/s:          1
Builder:         html
Config:          pages: 5, dummies: 20, sphinx: 5.1, folders: 0, depth: 1
Info:            #dummies: 100, #pages: 5, #indexes: 1, #folders: 0

Docs path:       /tmp/tmpubdjp65a
Docs files:      6 rst files with 8.67 kB
Docs setup:      0.02 s

Deps setup:      0.73 s

Build files:     41 files with 697.88 kB
File max️:        281.82 kB by /tmp/tmpubdjp65a/_build/_static/jquery-3.6.0.js
File min:        0.01 kB by /tmp/tmpubdjp65a/_build/_static/README
File Ø:          17.02 kB (0.02 s)
Reading time:    0.12 s
Writing time:    0.12 s
Build Duration:  0.92 s
─────────────────────────────────── RESULTS ────────────────────────────────────
╭───────────────┬───────────┬───────────┬───────────┬───────────╮
│       #       │   Run 1   │   Run 2   │   Run 3   │   Run 4   │
├───────────────┼───────────┼───────────┼───────────┼───────────┤
│    runtime    │   0.69    │   0.72    │   0.73    │   0.92    │
│    project    │   basic   │   basic   │   basic   │   basic   │
│               │           │           │           │           │
│    sphinx     │    5.1    │    5.1    │    5.1    │    5.1    │
│     pages     │     1     │     1     │     5     │     5     │
│     depth     │     1     │     1     │     1     │     1     │
│    folders    │     0     │     0     │     0     │     0     │
│    dummies    │     1     │    20     │     1     │    20     │
│    builder    │   html    │   html    │   html    │   html    │
│   parallel    │     1     │     1     │     1     │     1     │
│               │           │           │           │           │
│   #indexes    │     1     │     1     │     1     │     1     │
│    #pages     │     1     │     1     │     5     │     5     │
│   #dummies    │     1     │    20     │     5     │    100    │
│   #folders    │     0     │     0     │     0     │     0     │
│               │           │           │           │           │
│ writing time  │  0.05 s   │  0.06 s   │  0.08 s   │  0.12 s   │
│    # files    │    29     │    29     │    41     │    41     │
│ reading time  │  0.01 s   │  0.01 s   │  0.03 s   │  0.12 s   │
│ max file size │ 281.82 kB │ 281.82 kB │ 281.82 kB │ 281.82 kB │
│  folder size  │ 557.60 kB │ 577.60 kB │ 598.35 kB │ 697.88 kB │
│ avg file time │  0.02 s   │  0.02 s   │  0.02 s   │  0.02 s   │
│ min file size │  0.01 kB  │  0.01 kB  │  0.01 kB  │  0.01 kB  │
│ avg file size │ 19.23 kB  │ 19.92 kB  │ 14.59 kB  │ 17.02 kB  │
│               │           │           │           │           │
╰───────────────┴───────────┴───────────┴───────────┴───────────╯

Overall runtime: 3.06 seconds.

--temp

Defines the location of the folder to use for creating the temporary test project folders.

By default a operating system specific is chosen, on Linux this is /tmp.

--temp can also be a relative path.

So a sphinx-performance --temp . will create a test-folder like tmp0zmq3js2 in the current working directory.

Use --temp together with --keep, to keep the test-folder at an easy accessible location.

--debug

Shows the out put of Sphinx build and Python dependency installation step:

$ sphinx-performance --debug

Running 1 test configurations.


Running 1 test configurations.

─────────────────────────────────── Run 1/1 ────────────────────────────────────
Project:         basic
Core/s:          1
Builder:         html
Config:          sphinx: 5.1, dummies: 10, pages: 10, folders: 0, depth: 1
Info:            #dummies: 100, #pages: 10, #indexes: 1, #folders: 0

Docs path:       /tmp/tmp8aq5iuy0
Docs files:      11 rst files with 8.96 kB
Docs setup:      0.03 s

──────────────────────── Installing dependencies START ─────────────────────────
Requirement already satisfied: sphinx==5.1 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/latest/lib/python3.8/site-packages (from -r /tmp/tmp8aq5iuy0/requirements.txt (line 1)) (5.1.0)
Requirement already satisfied: sphinxcontrib-qthelp in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/latest/lib/python3.8/site-packages (from sphinx==5.1->-r /tmp/tmp8aq5iuy0/requirements.txt (line 1)) (1.0.3)
Requirement already satisfied: sphinxcontrib-serializinghtml>=1.1.5 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/latest/lib/python3.8/site-packages (from sphinx==5.1->-r /tmp/tmp8aq5iuy0/requirements.txt (line 1)) (1.1.5)
Requirement already satisfied: snowballstemmer>=1.1 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/latest/lib/python3.8/site-packages (from sphinx==5.1->-r /tmp/tmp8aq5iuy0/requirements.txt (line 1)) (2.2.0)
Requirement already satisfied: sphinxcontrib-applehelp in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/latest/lib/python3.8/site-packages (from sphinx==5.1->-r /tmp/tmp8aq5iuy0/requirements.txt (line 1)) (1.0.2)
Requirement already satisfied: babel>=1.3 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/latest/lib/python3.8/site-packages (from sphinx==5.1->-r /tmp/tmp8aq5iuy0/requirements.txt (line 1)) (2.10.3)
Requirement already satisfied: docutils<0.20,>=0.14 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/latest/lib/python3.8/site-packages (from sphinx==5.1->-r /tmp/tmp8aq5iuy0/requirements.txt (line 1)) (0.19)
Requirement already satisfied: Pygments>=2.0 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/latest/lib/python3.8/site-packages (from sphinx==5.1->-r /tmp/tmp8aq5iuy0/requirements.txt (line 1)) (2.13.0)
Requirement already satisfied: packaging in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/latest/lib/python3.8/site-packages (from sphinx==5.1->-r /tmp/tmp8aq5iuy0/requirements.txt (line 1)) (21.3)
Requirement already satisfied: requests>=2.5.0 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/latest/lib/python3.8/site-packages (from sphinx==5.1->-r /tmp/tmp8aq5iuy0/requirements.txt (line 1)) (2.28.1)
Requirement already satisfied: importlib-metadata>=4.4 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/latest/lib/python3.8/site-packages (from sphinx==5.1->-r /tmp/tmp8aq5iuy0/requirements.txt (line 1)) (5.0.0)
Requirement already satisfied: sphinxcontrib-devhelp in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/latest/lib/python3.8/site-packages (from sphinx==5.1->-r /tmp/tmp8aq5iuy0/requirements.txt (line 1)) (1.0.2)
Requirement already satisfied: imagesize in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/latest/lib/python3.8/site-packages (from sphinx==5.1->-r /tmp/tmp8aq5iuy0/requirements.txt (line 1)) (1.4.1)
Requirement already satisfied: alabaster<0.8,>=0.7 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/latest/lib/python3.8/site-packages (from sphinx==5.1->-r /tmp/tmp8aq5iuy0/requirements.txt (line 1)) (0.7.12)
Requirement already satisfied: sphinxcontrib-jsmath in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/latest/lib/python3.8/site-packages (from sphinx==5.1->-r /tmp/tmp8aq5iuy0/requirements.txt (line 1)) (1.0.1)
Requirement already satisfied: Jinja2>=2.3 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/latest/lib/python3.8/site-packages (from sphinx==5.1->-r /tmp/tmp8aq5iuy0/requirements.txt (line 1)) (3.1.2)
Requirement already satisfied: sphinxcontrib-htmlhelp>=2.0.0 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/latest/lib/python3.8/site-packages (from sphinx==5.1->-r /tmp/tmp8aq5iuy0/requirements.txt (line 1)) (2.0.0)
Requirement already satisfied: pytz>=2015.7 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/latest/lib/python3.8/site-packages (from babel>=1.3->sphinx==5.1->-r /tmp/tmp8aq5iuy0/requirements.txt (line 1)) (2022.5)
Requirement already satisfied: zipp>=0.5 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/latest/lib/python3.8/site-packages (from importlib-metadata>=4.4->sphinx==5.1->-r /tmp/tmp8aq5iuy0/requirements.txt (line 1)) (3.10.0)
Requirement already satisfied: MarkupSafe>=2.0 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/latest/lib/python3.8/site-packages (from Jinja2>=2.3->sphinx==5.1->-r /tmp/tmp8aq5iuy0/requirements.txt (line 1)) (2.1.1)
Requirement already satisfied: certifi>=2017.4.17 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/latest/lib/python3.8/site-packages (from requests>=2.5.0->sphinx==5.1->-r /tmp/tmp8aq5iuy0/requirements.txt (line 1)) (2022.9.24)
Requirement already satisfied: idna<4,>=2.5 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/latest/lib/python3.8/site-packages (from requests>=2.5.0->sphinx==5.1->-r /tmp/tmp8aq5iuy0/requirements.txt (line 1)) (3.4)
Requirement already satisfied: urllib3<1.27,>=1.21.1 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/latest/lib/python3.8/site-packages (from requests>=2.5.0->sphinx==5.1->-r /tmp/tmp8aq5iuy0/requirements.txt (line 1)) (1.26.12)
Requirement already satisfied: charset-normalizer<3,>=2 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/latest/lib/python3.8/site-packages (from requests>=2.5.0->sphinx==5.1->-r /tmp/tmp8aq5iuy0/requirements.txt (line 1)) (2.1.1)
Requirement already satisfied: pyparsing!=3.0.5,>=2.0.2 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/latest/lib/python3.8/site-packages (from packaging->sphinx==5.1->-r /tmp/tmp8aq5iuy0/requirements.txt (line 1)) (3.0.9)
─────────────────────── Installing dependencies FINISHED ───────────────────────
Deps setup:      0.74 s
Call:            /home/docs/checkouts/readthedocs.org/user_builds/sphinx-perform
ance/envs/latest/bin/sphinx-build -a -E -v -j 1 -b html /tmp/tmp8aq5iuy0 
/tmp/tmp8aq5iuy0/_build 
───────────────────────── Building documentation START ─────────────────────────
Running Sphinx v5.1.0
making output directory... done
locale_dir /tmp/tmp8aq5iuy0/locales/en/LC_MESSAGES does not exists
locale_dir /tmp/tmp8aq5iuy0/locales/en/LC_MESSAGES does not exists
locale_dir /tmp/tmp8aq5iuy0/locales/en/LC_MESSAGES does not exists
building [mo]: all of 0 po files
building [html]: all source files
updating environment: locale_dir /tmp/tmp8aq5iuy0/locales/en/LC_MESSAGES does not exists
[new config] 11 added, 0 changed, 0 removed
reading sources... [  9%] index
reading sources... [ 18%] page_0
reading sources... [ 27%] page_1
reading sources... [ 36%] page_2
reading sources... [ 45%] page_3
reading sources... [ 54%] page_4
reading sources... [ 63%] page_5
reading sources... [ 72%] page_6
reading sources... [ 81%] page_7
reading sources... [ 90%] page_8
reading sources... [100%] page_9

looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [  9%] index
writing output... [ 18%] page_0
writing output... [ 27%] page_1
writing output... [ 36%] page_2
writing output... [ 45%] page_3
writing output... [ 54%] page_4
writing output... [ 63%] page_5
writing output... [ 72%] page_6
writing output... [ 81%] page_7
writing output... [ 90%] page_8
writing output... [100%] page_9

generating indices... genindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in ../../../../../../../../../tmp/tmp8aq5iuy0/_build.
─────────────────────── Building documentation FINISHED ────────────────────────

Build files:     56 files with 746.88 kB
File max️:        281.82 kB by /tmp/tmp8aq5iuy0/_build/_static/jquery-3.6.0.js
File min:        0.01 kB by /tmp/tmp8aq5iuy0/_build/_static/README
File Ø:          13.34 kB (0.02 s)
Reading time:    0.00 s
Writing time:    0.00 s
Build Duration:  0.97 s

Deleting project /tmp/tmp8aq5iuy0/_build
─────────────────────────────────── RESULTS ────────────────────────────────────
╭───────────────┬───────────╮
│       #       │   Run 1   │
├───────────────┼───────────┤
│    runtime    │   0.97    │
│    project    │   basic   │
│               │           │
│    folders    │     0     │
│    sphinx     │    5.1    │
│     pages     │    10     │
│   parallel    │     1     │
│    builder    │   html    │
│     depth     │     1     │
│    dummies    │    10     │
│               │           │
│   #dummies    │    100    │
│   #indexes    │     1     │
│   #folders    │     0     │
│    #pages     │    10     │
│               │           │
│ reading time  │  0.00 s   │
│  folder size  │ 746.88 kB │
│    # files    │    56     │
│ avg file time │  0.02 s   │
│ max file size │ 281.82 kB │
│ avg file size │ 13.34 kB  │
│ min file size │  0.01 kB  │
│ writing time  │  0.00 s   │
│               │           │
╰───────────────┴───────────╯

Overall runtime: 0.97 seconds.

--keep

Does not delete the created, temporary test folders and prints their location.

$ sphinx-performance --keep

Running 1 test configurations.


Running 1 test configurations.

─────────────────────────────────── Run 1/1 ────────────────────────────────────
Project:         basic
Core/s:          1
Builder:         html
Config:          sphinx: 5.1, dummies: 10, pages: 10, folders: 0, depth: 1
Info:            #dummies: 100, #pages: 10, #indexes: 1, #folders: 0

Docs path:       /tmp/tmpdhnim4z9
Docs files:      11 rst files with 8.96 kB
Docs setup:      0.03 s

Deps setup:      0.73 s

Build files:     56 files with 746.88 kB
File max️:        281.82 kB by /tmp/tmpdhnim4z9/_build/_static/jquery-3.6.0.js
File min:        0.01 kB by /tmp/tmpdhnim4z9/_build/_static/README
File Ø:          13.34 kB (0.02 s)
Reading time:    0.15 s
Writing time:    0.19 s
Build Duration:  0.99 s
─────────────────────────────────── RESULTS ────────────────────────────────────
╭───────────────┬───────────╮
│       #       │   Run 1   │
├───────────────┼───────────┤
│    runtime    │   0.99    │
│    project    │   basic   │
│               │           │
│    dummies    │    10     │
│    builder    │   html    │
│    sphinx     │    5.1    │
│     pages     │    10     │
│    folders    │     0     │
│     depth     │     1     │
│   parallel    │     1     │
│               │           │
│   #folders    │     0     │
│   #indexes    │     1     │
│   #dummies    │    100    │
│    #pages     │    10     │
│               │           │
│ max file size │ 281.82 kB │
│ avg file time │  0.02 s   │
│  folder size  │ 746.88 kB │
│ reading time  │  0.15 s   │
│ writing time  │  0.19 s   │
│ avg file size │ 13.34 kB  │
│ min file size │  0.01 kB  │
│    # files    │    56     │
│               │           │
╰───────────────┴───────────╯

Overall runtime: 0.99 seconds.

--browser

Opens each generated documentation in the browser after the build:

sphinx-performance --browser

This sets also automatically --keep.

--csv

Stores the result table in a given CSV-file

If the file exists, it gets overwritten:

sphinx-performance –csv results.csv

sphinx-analysis

sphinx-analysis builds a single project, but is able to create runtime and memory profiles of the Sphinx build. It also allows to present the profiled data in different views, like tables, flamegraphs and summaries.

For runtime profiling, cProfile is used. memray is the used memory profiler, which also supports a live viewer.

Warning

Don’t use more than one profiler at the same time, as they would influence each other. It’s better to reuse the same project config and just replace the profiler.

The options for setting up the project are the same as for sphinx-performance, except csv, which is not supported, and snakeviz, which was renamed to flamegraph.

Example calls:

sphinx-analysis --project --pages 10 --folders 3 --depth 2 --memray --flamegraph
sphinx-analysis --project --pages 10 --folders 3 --depth 2 --runtime --stats
sphinx-analysis --project needs --needs 40 --needtables 2 --pages 5 --folders 2 --depth 1 --pyinstrument --tree
sphinx-analysis --ref medium --runtime --summary

--runtime

Starts the runtime profiling of the Sphinx build. Results are stored inside the file runtime_all.prof.

--memray

Profiles the memory consumption of the Sphinx build. Results are stored in the file memray_all.prof.

--memray-live

Nearly same as --memray, but waits with the profiling till a memray viewer is connected. Creates no result file.

A memray viewer can be opened in another terminal by executing memray live 13167.

--pyinstrument

Uses the pyinstrument profiler and saves the profile in a file called pyinstrument_profile.json.

--stats

Prints some statistics at the end of the build.

Supported by: --runtime and --memray.

runtime stats

memray stats

--summary

Prints the memray summary at the end of the build.

Supported by: --memray.

memray summary

--flamegraph

Opens a browser to show a flamegraph view of the captured profile.

For runtime snakeviz is used, and for memray the memray flamegraph.

Supported by: --runtime and --memray.

runtime flamegraph

memray flamegraph

--silent

Can be used to answer questions to the user automatically with yes.

This may happen, if e.g. multiple projects are configured to be used, and sphinx-analysis asks the user to confirm this.

-- tree

Creates a pyinstrument_profile.html file, which shows a runtime tree, profiled by --pyinstrument.

Supported by: --pyinstrument.

pyinstrument tree in HTML file