sphinx-doc / sphinx-doc/sphinx
:numref: does not work in files included with "include" directive
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Describe the bug
We have an .rst file that includes four other files. Inside these other files, we have figures that we reference using :numref:. However, on building, we get the "Failed to create a cross reference. Any number is not assigned" error (for each image), and references are not created correctly in the HTML file. What's strange is that 1. using :ref: alone works perfectly and 2. the captions with figure numbers are being generated correctly. It's only the numeric references that don't work.
Something that's perhaps worth pointing out is that, technically, the paths to which our figures point don't exist, because we have our images separated into folders by language. That is, the path in the figure points to some/path while the image is actually in some/path/language. However, this is also done in every other file we have and there are no problems.
How to Reproduce
Download sample.zip and run ./make.bat html. Open 15-BPMWeb.html for the problem file. 19-SAMWeb.html works fine.
sample.zip
Expected behavior
The references to the figures are generated correctly.
Your project
Screenshots
No response
OS
Windows
Python version
3.9.2
Sphinx version
3.5.1
Sphinx extensions
'recommonmark', 'sphinx.ext.autosectionlabel'
Extra tools
No response
Additional context
No response
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by extracting sample.zip and running ./make.bat html on Windows, then compare 15-BPMWeb.html with 19-SAMWeb.html. Trace how :numref: is resolved for figures in files included by the include directive, using the working :ref: output and generated figure captions as comparison points. Done means numeric figure references render correctly in the HTML output.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100