sphinx-numref-performance
sphinx-numref-performance makes Sphinx resolve :numref: references without loading the doctree of the document that holds the target. It exists to provide community testing for a fix to sphinx-doc/sphinx#12611 and is meant to be retired once a Sphinx release contains that fix.
Sphinx resolves each reference by unpickling a fresh copy of the target document, so a page with many references into large documents costs time proportional to the number of references multiplied by the size of those documents. The effect is easiest to see on a page carrying many numbered tables or figures:
page |
Sphinx |
extension |
|---|---|---|
50 captioned tables and references |
1.00s |
0.43s |
100 captioned tables and references |
3.39s |
0.60s |
200 captioned tables and references |
16.31s |
1.06s |
Reproduce those numbers on your own machine with tox -e bench.
Installation
Install the package and add it to conf.py:
extensions = [
"sphinx_numref_performance",
]Then build normally. Every builder benefits, and no other configuration is needed.
The first build after enabling or removing the extension reads all documents again, because the extension keeps data in the build environment.
Output
The extension changes build time only. Sphinx’s own resolver still formats every reference and emits every warning, so numbers, titles, numfig_format handling, and warnings such as numfig is disabled are unchanged. The test suite asserts that HTML and LaTeX output is identical to a build without the extension.
Documentation
See the documentation for how the extension works, its compatibility, and how to measure it.
Development
Run the tests, static checks, and documentation build:
toxThe matrix covers Sphinx 8.1, 8.2, and 9.1.
1 maintainer
Metadata
1 maintainer
Release files for sphinx-numref-performance 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| sphinx_numref_performance-0.1.0.tar.gz | 16.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| sphinx_numref_performance-0.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 23.6 kB
Release files / sphinx_numref_performance-0.1.0.tar.gz
| Download URL | sphinx_numref_performance-0.1.0.tar.gz |
|---|---|
| Size | 16.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4080507cfa091d51f838df236318f28a7b607bfb2666c7918124d296844bb3a7
|
|
BLAKE2b-256 checksum How to use checksums |
ae27a65a52485a5a1df1c131002b9d2b94bd446a3136aee9e48ee6587f241ca5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.0
|
Release files / sphinx_numref_performance-0.1.0-py3-none-any.whl
| Download URL | sphinx_numref_performance-0.1.0-py3-none-any.whl |
|---|---|
| Size | 7.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3e39cadd701faa84abd4c5efad166cd1e5ae135a88aeac50293e0c4c329d3fcf
|
|
BLAKE2b-256 checksum How to use checksums |
9fa566fa9bf1592a53b71f720b1eb58252f3eabcc439e897ea15dcb8aa5dda36
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.0
|
