sphinx-doc / sphinx-doc/sphinx

:numref: does not work in files included with "include" directive

Open
#9,779 3 comments 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

type:bug
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

sample.zip

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.