Metadata-Version: 2.4
Name: sphinx-numref-performance
Version: 0.1.0
Summary: Resolve Sphinx :numref: references without loading the target doctree
Author: Jared Dillard
License-Expression: BSD-2-Clause
Project-URL: Documentation, https://sphinx-numref-performance.readthedocs.io/
Project-URL: Issues, https://github.com/jdillard/sphinx-numref-performance/issues
Project-URL: Source, https://github.com/jdillard/sphinx-numref-performance
Classifier: Framework :: Sphinx
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Documentation :: Sphinx
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: Sphinx<10,>=8.1
Provides-Extra: docs
Requires-Dist: furo>=2024.8.6; extra == "docs"
Dynamic: license-file

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 <https://github.com/sphinx-doc/sphinx/issues/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``:

.. code-block:: python

   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 <https://sphinx-numref-performance.readthedocs.io/>`_
for how the extension works, its compatibility, and how to measure it.

Development
-----------

Run the tests, static checks, and documentation build:

.. code-block:: console

   tox

The matrix covers Sphinx 8.1, 8.2, and 9.1.
