Sphinx-Performance

Sphinx-Performance is a Commandline tool to analyse the performance of different Sphinx documentation project setups.

It was created to answer questions like:

• How well does Sphinx scale?

• What impact does a specific extension have to the build time?

• Is there any different between two specific versions?

• How huge is the benefit of using parallel build mode?

• What are the performance bottlenecks during a Sphinx build?

• What functions have an impact on the runtime?

• Are there any memory problems?

• How does my Sphinx extension perform?

• What runtime is consumed by Sphinx events?

To answer these questions, two commandline tools are provided:

sphinx-performance

Used to create automatically different projects and compare their build time and other key numbers.

See sphinx-performance for details.

sphinx-analysis

Provides profilers and different viewers for runtime and memory consumption.

See sphinx-analysis for details.

Note

Based on the used test project, sphinx-performance may install specific library versions into the currently used Python environment.

It is a good idea to use virtual environments for sphinx-performance runs.

Contents:

• Installation
• CLI
  • sphinx-performance
    • --project
    • --parallel
    • --builder
    • Project parameters
    • --temp
    • --debug
    • --keep
    • --browser
    • --csv
  • sphinx-analysis
    • --runtime
    • --memray
    • --memray-live
    • --pyinstrument
    • --stats
    • --summary
    • --flamegraph
    • --silent
    • --tree
    • -- tree-filter
    • --sphinx-events
• Test Projects
  • Integrated test project
    • Basic
    • Needs
    • Theme
  • Own test projects
    • jinja support
    • performance.py
    • conf.template
    • index.template
    • page.template
    • requirements.template
    • __static folder

Kudos

This little tool borrows a lot of ideas from the performance script of Sphinx-Needs.

Changelog

0.1.8

Released:

under development

• Improvement: Adds --pyinstrument as an additional profiler to sphinx-analysis.

0.1.7

Released:

27.10.2022

• Improvement: Introducing sphinx-analysis for runtime and memory profiling.

• Improvement: --project can be used multiple times.

• Bugfix: Python bin/script calculation on windows fixed.

0.1.6

Released:

21.02.2022

• Improvement: Reading and writing times get measured (ALPHA status, poor parallel build support).

• Improvement: CSV export is possible by setting --csv results.csv.

• Improvement: Builder can be set, also multiple times: --builder json.

0.1.5

Released:

18.02.2022

• Improvement: --temp parameter support

• Improvement: Result tables highlights diffs

• Improvement: More data for result tables

• Bugfix: Unique Needs ID calculation

0.1.4

Released:

17.02.2022

• Bugfix: “Need” project unique object-id calculation working with folders.

• Bugfix: “Need” project defines all needed defaults now.

0.1.3

Released:

17.02.2022

• Improvement: More data (File amounts and sizes, build times, progress timer)

• Improvement: Amount of folders can be defined

• Improvement: Folder depth can be defined

• Improvement: Folder support for test projects

0.1.2

Released:

16.02.2022

• Initial version