CLI¶

sphinx-performance
sphinx-analysis

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: 4.2, dummies: 10, folders: 0, depth: 1
Info:            #dummies: 300, #pages: 30, #indexes: 1, #folders: 0

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

Deps setup:      1.91 s

Build files:     115 files with 1212.41 kB
File max️:        280.89 kB by /tmp/tmpc9u2mok_/_build/_static/jquery-3.5.1.js
File min:        0.01 kB by /tmp/tmpc9u2mok_/_build/_static/README
File Ø:          10.54 kB (0.02 s)
Reading time:    0.57 s
Writing time:    0.82 s
Build Duration:  2.08 s
─────────────────────────────────── Run 2/2 ────────────────────────────────────
Project:         basic
Core/s:          4
Builder:         html
Config:          pages: 30, sphinx: 4.2, dummies: 10, folders: 0, depth: 1
Info:            #dummies: 300, #pages: 30, #indexes: 1, #folders: 0

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

Deps setup:      0.72 s

Build files:     115 files with 1213.26 kB
File max️:        280.89 kB by /tmp/tmp7tieb572/_build/_static/jquery-3.5.1.js
File min:        0.01 kB by /tmp/tmp7tieb572/_build/_static/README
File Ø:          10.55 kB (0.02 s)
Reading time:    0.10 s
Writing time:    0.14 s
Build Duration:  2.28 s
─────────────────────────────────── RESULTS ────────────────────────────────────
╭───────────────┬────────────┬────────────╮
│       #       │   Run 1    │   Run 2    │
├───────────────┼────────────┼────────────┤
│    runtime    │    2.08    │    2.28    │
│    project    │   basic    │   basic    │
│               │            │            │
│    builder    │    html    │    html    │
│    folders    │     0      │     0      │
│    sphinx     │    4.2     │    4.2     │
│   parallel    │     1      │     4      │
│     depth     │     1      │     1      │
│    dummies    │     10     │     10     │
│     pages     │     30     │     30     │
│               │            │            │
│    #pages     │     30     │     30     │
│   #folders    │     0      │     0      │
│   #indexes    │     1      │     1      │
│   #dummies    │    300     │    300     │
│               │            │            │
│    # files    │    115     │    115     │
│ writing time  │   0.82 s   │   0.14 s   │
│ avg file time │   0.02 s   │   0.02 s   │
│  folder size  │ 1212.41 kB │ 1213.26 kB │
│ max file size │ 280.89 kB  │ 280.89 kB  │
│ min file size │  0.01 kB   │  0.01 kB   │
│ avg file size │  10.54 kB  │  10.55 kB  │
│ reading time  │   0.57 s   │   0.10 s   │
│               │            │            │
╰───────────────┴────────────┴────────────╯

Overall runtime: 4.36 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: 4.2, dummies: 10, folders: 0, depth: 1
Info:            #dummies: 20, #pages: 2, #indexes: 1, #folders: 0

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

Deps setup:      0.71 s

Build files:     31 files with 587.89 kB
File max️:        280.89 kB by /tmp/tmp4gv1mem2/_build/_static/jquery-3.5.1.js
File min:        0.01 kB by /tmp/tmp4gv1mem2/_build/_static/README
File Ø:          18.96 kB (0.02 s)
Reading time:    0.04 s
Writing time:    0.08 s
Build Duration:  0.76 s
─────────────────────────────────── Run 2/2 ────────────────────────────────────
Project:         basic
Core/s:          1
Builder:         text
Config:          pages: 2, sphinx: 4.2, dummies: 10, folders: 0, depth: 1
Info:            #dummies: 20, #pages: 2, #indexes: 1, #folders: 0

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

Deps setup:      0.71 s

Build files:     7 files with 43.05 kB
File max️:        14.34 kB by 
/tmp/tmpqhikqdiz/_build/.doctrees/environment.pickle
File min:        0.32 kB by /tmp/tmpqhikqdiz/_build/index.txt
File Ø:          6.15 kB (0.08 s)
Reading time:    0.03 s
Writing time:    0.01 s
Build Duration:  0.59 s
─────────────────────────────────── RESULTS ────────────────────────────────────
╭───────────────┬───────────┬──────────╮
│       #       │   Run 1   │  Run 2   │
├───────────────┼───────────┼──────────┤
│    runtime    │   0.76    │   0.59   │
│    project    │   basic   │  basic   │
│               │           │          │
│    sphinx     │    4.2    │   4.2    │
│    folders    │     0     │    0     │
│    builder    │   html    │   text   │
│     depth     │     1     │    1     │
│   parallel    │     1     │    1     │
│     pages     │     2     │    2     │
│    dummies    │    10     │    10    │
│               │           │          │
│   #folders    │     0     │    0     │
│    #pages     │     2     │    2     │
│   #indexes    │     1     │    1     │
│   #dummies    │    20     │    20    │
│               │           │          │
│ avg file size │ 18.96 kB  │ 6.15 kB  │
│ min file size │  0.01 kB  │ 0.32 kB  │
│ avg file time │  0.02 s   │  0.08 s  │
│ max file size │ 280.89 kB │ 14.34 kB │
│  folder size  │ 587.89 kB │ 43.05 kB │
│ writing time  │  0.08 s   │  0.01 s  │
│    # files    │    31     │    7     │
│ reading time  │  0.04 s   │  0.03 s  │
│               │           │          │
╰───────────────┴───────────┴──────────╯

Overall runtime: 1.35 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: 4.2, folders: 0, depth: 1
Info:            #dummies: 10, #pages: 2, #indexes: 1, #folders: 0

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

Deps setup:      0.72 s

Build files:     31 files with 576.94 kB
File max️:        280.89 kB by /tmp/tmp6m1z2hcj/_build/_static/jquery-3.5.1.js
File min:        0.01 kB by /tmp/tmp6m1z2hcj/_build/_static/README
File Ø:          18.61 kB (0.02 s)
Reading time:    0.03 s
Writing time:    0.08 s
Build Duration:  0.76 s
─────────────────────────────────── RESULTS ────────────────────────────────────
╭───────────────┬───────────╮
│       #       │   Run 1   │
├───────────────┼───────────┤
│    runtime    │   0.76    │
│    project    │   basic   │
│               │           │
│    sphinx     │    4.2    │
│    builder    │   html    │
│    folders    │     0     │
│   parallel    │     1     │
│     depth     │     1     │
│    dummies    │     5     │
│     pages     │     2     │
│               │           │
│   #indexes    │     1     │
│    #pages     │     2     │
│   #folders    │     0     │
│   #dummies    │    10     │
│               │           │
│ avg file size │ 18.61 kB  │
│  folder size  │ 576.94 kB │
│ max file size │ 280.89 kB │
│    # files    │    31     │
│ reading time  │  0.03 s   │
│ min file size │  0.01 kB  │
│ writing time  │  0.08 s   │
│ avg file time │  0.02 s   │
│               │           │
╰───────────────┴───────────╯

Overall runtime: 0.76 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

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:

pages = 1 and dummies = 1

pages = 1 and dummies = 20

pages = 5 and dummies = 1

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: 4.2, folders: 0, depth: 1
Info:            #dummies: 1, #pages: 1, #indexes: 1, #folders: 0

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

Deps setup:      0.70 s

Build files:     28 files with 558.25 kB
File max️:        280.89 kB by /tmp/tmprep4ea5v/_build/_static/jquery-3.5.1.js
File min:        0.01 kB by /tmp/tmprep4ea5v/_build/_static/README
File Ø:          19.94 kB (0.03 s)
Reading time:    0.02 s
Writing time:    0.06 s
Build Duration:  0.71 s
─────────────────────────────────── Run 2/4 ────────────────────────────────────
Project:         basic
Core/s:          1
Builder:         html
Config:          pages: 1, dummies: 20, sphinx: 4.2, folders: 0, depth: 1
Info:            #dummies: 20, #pages: 1, #indexes: 1, #folders: 0

Docs path:       /tmp/tmp9_9a6c3j
Docs files:      2 rst files with 1.88 kB
Docs setup:      0.01 s

Deps setup:      0.71 s

Build files:     28 files with 579.21 kB
File max️:        280.89 kB by /tmp/tmp9_9a6c3j/_build/_static/jquery-3.5.1.js
File min:        0.01 kB by /tmp/tmp9_9a6c3j/_build/_static/README
File Ø:          20.69 kB (0.03 s)
Reading time:    0.02 s
Writing time:    0.06 s
Build Duration:  0.78 s
─────────────────────────────────── Run 3/4 ────────────────────────────────────
Project:         basic
Core/s:          1
Builder:         html
Config:          pages: 5, dummies: 1, sphinx: 4.2, folders: 0, depth: 1
Info:            #dummies: 5, #pages: 5, #indexes: 1, #folders: 0

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

Deps setup:      0.71 s

Build files:     40 files with 598.87 kB
File max️:        280.89 kB by /tmp/tmp1ds_bej5/_build/_static/jquery-3.5.1.js
File min:        0.01 kB by /tmp/tmp1ds_bej5/_build/_static/README
File Ø:          14.97 kB (0.02 s)
Reading time:    0.04 s
Writing time:    0.13 s
Build Duration:  0.82 s
─────────────────────────────────── Run 4/4 ────────────────────────────────────
Project:         basic
Core/s:          1
Builder:         html
Config:          pages: 5, dummies: 20, sphinx: 4.2, folders: 0, depth: 1
Info:            #dummies: 100, #pages: 5, #indexes: 1, #folders: 0

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

Deps setup:      0.72 s

Build files:     40 files with 703.34 kB
File max️:        280.89 kB by /tmp/tmpfqzdlun9/_build/_static/jquery-3.5.1.js
File min:        0.01 kB by /tmp/tmpfqzdlun9/_build/_static/README
File Ø:          17.58 kB (0.02 s)
Reading time:    0.15 s
Writing time:    0.16 s
Build Duration:  0.99 s
─────────────────────────────────── RESULTS ────────────────────────────────────
╭───────────────┬───────────┬───────────┬───────────┬───────────╮
│       #       │   Run 1   │   Run 2   │   Run 3   │   Run 4   │
├───────────────┼───────────┼───────────┼───────────┼───────────┤
│    runtime    │   0.71    │   0.78    │   0.82    │   0.99    │
│    project    │   basic   │   basic   │   basic   │   basic   │
│               │           │           │           │           │
│   parallel    │     1     │     1     │     1     │     1     │
│    folders    │     0     │     0     │     0     │     0     │
│    dummies    │     1     │    20     │     1     │    20     │
│    sphinx     │    4.2    │    4.2    │    4.2    │    4.2    │
│    builder    │   html    │   html    │   html    │   html    │
│     pages     │     1     │     1     │     5     │     5     │
│     depth     │     1     │     1     │     1     │     1     │
│               │           │           │           │           │
│   #dummies    │     1     │    20     │     5     │    100    │
│   #indexes    │     1     │     1     │     1     │     1     │
│    #pages     │     1     │     1     │     5     │     5     │
│   #folders    │     0     │     0     │     0     │     0     │
│               │           │           │           │           │
│    # files    │    28     │    28     │    40     │    40     │
│ reading time  │  0.02 s   │  0.02 s   │  0.04 s   │  0.15 s   │
│ max file size │ 280.89 kB │ 280.89 kB │ 280.89 kB │ 280.89 kB │
│  folder size  │ 558.25 kB │ 579.21 kB │ 598.87 kB │ 703.34 kB │
│ min file size │  0.01 kB  │  0.01 kB  │  0.01 kB  │  0.01 kB  │
│ avg file size │ 19.94 kB  │ 20.69 kB  │ 14.97 kB  │ 17.58 kB  │
│ avg file time │  0.03 s   │  0.03 s   │  0.02 s   │  0.02 s   │
│ writing time  │  0.06 s   │  0.06 s   │  0.13 s   │  0.16 s   │
│               │           │           │           │           │
╰───────────────┴───────────┴───────────┴───────────┴───────────╯

Overall runtime: 3.30 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: 4.2, dummies: 10, pages: 10, folders: 0, depth: 1
Info:            #dummies: 100, #pages: 10, #indexes: 1, #folders: 0

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

──────────────────────── Installing dependencies START ─────────────────────────
Requirement already satisfied: sphinx==4.2 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/stable/lib/python3.8/site-packages (from -r /tmp/tmpao97ewil/requirements.txt (line 1)) (4.2.0)
Requirement already satisfied: Pygments>=2.0 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/stable/lib/python3.8/site-packages (from sphinx==4.2->-r /tmp/tmpao97ewil/requirements.txt (line 1)) (2.13.0)
Requirement already satisfied: sphinxcontrib-serializinghtml>=1.1.5 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/stable/lib/python3.8/site-packages (from sphinx==4.2->-r /tmp/tmpao97ewil/requirements.txt (line 1)) (1.1.5)
Requirement already satisfied: alabaster<0.8,>=0.7 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/stable/lib/python3.8/site-packages (from sphinx==4.2->-r /tmp/tmpao97ewil/requirements.txt (line 1)) (0.7.12)
Requirement already satisfied: setuptools in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/stable/lib/python3.8/site-packages (from sphinx==4.2->-r /tmp/tmpao97ewil/requirements.txt (line 1)) (58.2.0)
Requirement already satisfied: sphinxcontrib-applehelp in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/stable/lib/python3.8/site-packages (from sphinx==4.2->-r /tmp/tmpao97ewil/requirements.txt (line 1)) (1.0.2)
Requirement already satisfied: imagesize in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/stable/lib/python3.8/site-packages (from sphinx==4.2->-r /tmp/tmpao97ewil/requirements.txt (line 1)) (1.4.1)
Requirement already satisfied: babel>=1.3 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/stable/lib/python3.8/site-packages (from sphinx==4.2->-r /tmp/tmpao97ewil/requirements.txt (line 1)) (2.10.3)
Requirement already satisfied: sphinxcontrib-jsmath in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/stable/lib/python3.8/site-packages (from sphinx==4.2->-r /tmp/tmpao97ewil/requirements.txt (line 1)) (1.0.1)
Requirement already satisfied: sphinxcontrib-qthelp in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/stable/lib/python3.8/site-packages (from sphinx==4.2->-r /tmp/tmpao97ewil/requirements.txt (line 1)) (1.0.3)
Requirement already satisfied: sphinxcontrib-htmlhelp>=2.0.0 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/stable/lib/python3.8/site-packages (from sphinx==4.2->-r /tmp/tmpao97ewil/requirements.txt (line 1)) (2.0.0)
Requirement already satisfied: snowballstemmer>=1.1 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/stable/lib/python3.8/site-packages (from sphinx==4.2->-r /tmp/tmpao97ewil/requirements.txt (line 1)) (2.2.0)
Requirement already satisfied: sphinxcontrib-devhelp in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/stable/lib/python3.8/site-packages (from sphinx==4.2->-r /tmp/tmpao97ewil/requirements.txt (line 1)) (1.0.2)
Requirement already satisfied: packaging in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/stable/lib/python3.8/site-packages (from sphinx==4.2->-r /tmp/tmpao97ewil/requirements.txt (line 1)) (21.3)
Requirement already satisfied: Jinja2>=2.3 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/stable/lib/python3.8/site-packages (from sphinx==4.2->-r /tmp/tmpao97ewil/requirements.txt (line 1)) (3.1.2)
Requirement already satisfied: requests>=2.5.0 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/stable/lib/python3.8/site-packages (from sphinx==4.2->-r /tmp/tmpao97ewil/requirements.txt (line 1)) (2.28.1)
Requirement already satisfied: docutils<0.18,>=0.14 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/stable/lib/python3.8/site-packages (from sphinx==4.2->-r /tmp/tmpao97ewil/requirements.txt (line 1)) (0.17.1)
Requirement already satisfied: pytz>=2015.7 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/stable/lib/python3.8/site-packages (from babel>=1.3->sphinx==4.2->-r /tmp/tmpao97ewil/requirements.txt (line 1)) (2022.5)
Requirement already satisfied: MarkupSafe>=2.0 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/stable/lib/python3.8/site-packages (from Jinja2>=2.3->sphinx==4.2->-r /tmp/tmpao97ewil/requirements.txt (line 1)) (2.1.1)
Requirement already satisfied: idna<4,>=2.5 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/stable/lib/python3.8/site-packages (from requests>=2.5.0->sphinx==4.2->-r /tmp/tmpao97ewil/requirements.txt (line 1)) (3.4)
Requirement already satisfied: charset-normalizer<3,>=2 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/stable/lib/python3.8/site-packages (from requests>=2.5.0->sphinx==4.2->-r /tmp/tmpao97ewil/requirements.txt (line 1)) (2.1.1)
Requirement already satisfied: urllib3<1.27,>=1.21.1 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/stable/lib/python3.8/site-packages (from requests>=2.5.0->sphinx==4.2->-r /tmp/tmpao97ewil/requirements.txt (line 1)) (1.26.12)
Requirement already satisfied: certifi>=2017.4.17 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/stable/lib/python3.8/site-packages (from requests>=2.5.0->sphinx==4.2->-r /tmp/tmpao97ewil/requirements.txt (line 1)) (2022.9.24)
Requirement already satisfied: pyparsing!=3.0.5,>=2.0.2 in /home/docs/checkouts/readthedocs.org/user_builds/sphinx-performance/envs/stable/lib/python3.8/site-packages (from packaging->sphinx==4.2->-r /tmp/tmpao97ewil/requirements.txt (line 1)) (3.0.9)
─────────────────────── Installing dependencies FINISHED ───────────────────────
Deps setup:      0.71 s
Call:            /home/docs/checkouts/readthedocs.org/user_builds/sphinx-perform
ance/envs/stable/bin/sphinx-build -a -E -v -j 1 -b html /tmp/tmpao97ewil 
/tmp/tmpao97ewil/_build 
───────────────────────── Building documentation START ─────────────────────────
Running Sphinx v4.2.0
making output directory... done
building [mo]: all of 0 po files
building [html]: all source files
updating environment: [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/tmpao97ewil/_build.
─────────────────────── Building documentation FINISHED ────────────────────────

Build files:     55 files with 751.89 kB
File max️:        280.89 kB by /tmp/tmpao97ewil/_build/_static/jquery-3.5.1.js
File min:        0.01 kB by /tmp/tmpao97ewil/_build/_static/README
File Ø:          13.67 kB (0.02 s)
Reading time:    0.00 s
Writing time:    0.00 s
Build Duration:  1.10 s

Deleting project /tmp/tmpao97ewil/_build
─────────────────────────────────── RESULTS ────────────────────────────────────
╭───────────────┬───────────╮
│       #       │   Run 1   │
├───────────────┼───────────┤
│    runtime    │   1.10    │
│    project    │   basic   │
│               │           │
│     pages     │    10     │
│   parallel    │     1     │
│    sphinx     │    4.2    │
│     depth     │     1     │
│    builder    │   html    │
│    folders    │     0     │
│    dummies    │    10     │
│               │           │
│    #pages     │    10     │
│   #indexes    │     1     │
│   #folders    │     0     │
│   #dummies    │    100    │
│               │           │
│    # files    │    55     │
│ max file size │ 280.89 kB │
│ min file size │  0.01 kB  │
│  folder size  │ 751.89 kB │
│ writing time  │  0.00 s   │
│ avg file time │  0.02 s   │
│ avg file size │ 13.67 kB  │
│ reading time  │  0.00 s   │
│               │           │
╰───────────────┴───────────╯

Overall runtime: 1.10 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: 4.2, dummies: 10, pages: 10, folders: 0, depth: 1
Info:            #dummies: 100, #pages: 10, #indexes: 1, #folders: 0

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

Deps setup:      0.71 s

Build files:     55 files with 751.89 kB
File max️:        280.89 kB by /tmp/tmpbgt2o_6d/_build/_static/jquery-3.5.1.js
File min:        0.01 kB by /tmp/tmpbgt2o_6d/_build/_static/README
File Ø:          13.67 kB (0.02 s)
Reading time:    0.18 s
Writing time:    0.27 s
Build Duration:  1.10 s
─────────────────────────────────── RESULTS ────────────────────────────────────
╭───────────────┬───────────╮
│       #       │   Run 1   │
├───────────────┼───────────┤
│    runtime    │   1.10    │
│    project    │   basic   │
│               │           │
│    sphinx     │    4.2    │
│    folders    │     0     │
│   parallel    │     1     │
│    dummies    │    10     │
│     pages     │    10     │
│     depth     │     1     │
│    builder    │   html    │
│               │           │
│   #folders    │     0     │
│   #indexes    │     1     │
│    #pages     │    10     │
│   #dummies    │    100    │
│               │           │
│ min file size │  0.01 kB  │
│    # files    │    55     │
│ writing time  │  0.27 s   │
│ reading time  │  0.18 s   │
│ max file size │ 280.89 kB │
│ avg file size │ 13.67 kB  │
│  folder size  │ 751.89 kB │
│ avg file time │  0.02 s   │
│               │           │
╰───────────────┴───────────╯

Overall runtime: 1.10 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 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.

--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.

--stats¶

Prints some statistics at the end of the build.

Supported by: --runtime and --memray.

_images/runtime_stats.png — runtime stats¶

_images/memray_stats.png — memray stats¶

--summary¶

Prints the memray summary at the end of the build.

Supported by: --memray.

_images/memray_summary.png — 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.

_images/runtime_flamegraph.png — runtime flamegraph¶

_images/memray_flamegraph.png — 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.

Navigation

Related Topics

CLI¶

sphinx-performance ¶

--project¶

--parallel¶

--builder¶

Project parameters¶

Commonly used parameters¶

--pages¶

--folders¶

--depth¶

Parameter matrix¶

--temp¶

--debug¶

--keep¶

--browser¶

--csv¶

sphinx-analysis ¶

--runtime¶

--memray¶

--memray-live¶

--stats¶

--summary¶

--flamegraph¶

--silent¶

CLI¶

sphinx-performance¶

--project¶

--parallel¶

--builder¶

Project parameters¶

Commonly used parameters¶

--pages¶

--folders¶

--depth¶

Parameter matrix¶

--temp¶

--debug¶

--keep¶

--browser¶

--csv¶

sphinx-analysis¶

--runtime¶

--memray¶

--memray-live¶

--stats¶

--summary¶

--flamegraph¶

--silent¶

sphinx-performance ¶

sphinx-analysis ¶