How to cache man builder output #13727
Description
Describe the bug
Man pages are always recreated even if sources did not change.
I'd like to understand why, and find out what's the recommended way (if any) of caching man pages.
Maybe the man builder depends on some external program, where we err on the side of rebuilding?
For context: fish shell wants to speed up incremental sphinx manpage builds because we configured cargo build to run sphinx-build by default.
How to Reproduce
$ echo >conf.py 'author = "A. U. Thor"
man_pages = [
("index", "index-man", "", [author], 1),
]'
$ mkdir src
$ echo >src/index.rst 'test content'
$ while sleep .5; do
sphinx-build --conf-dir=. --doctree-dir=out-doctrees src -b man out-manpages >/dev/null
done &
$ while sleep 1; do
stat out-manpages/index-man.1 | grep Modify
doneobserve that index-man.1's modification timestamp keeps changing.
When using -b html instead, we can observe that the HTML builder also updates some files everytime, but it does not update out-*/index.html,
so it seems to be smarter than the man builder?
Environment Information
Platform: linux; (Linux-6.15.3-arch1-1-x86_64-with-glibc2.41)
Python version: 3.13.5 (main, Jun 21 2025, 09:35:00) [GCC 15.1.1 20250425])
Python implementation: CPython
Sphinx version: 8.2.3
Docutils version: 0.21.2
Jinja2 version: 3.1.6
Pygments version: 2.19.2
Sphinx extensions
Additional context
No response