sphinx
sphinx copied to clipboard
Label after 'only' directive not found for xref
Describe the bug
I'm getting the following error:
Failed to create a cross reference. A title or caption not found: troubleshooting
For a cross-reference to a label that appears after .. only
directive:
See: :ref:`troubleshooting`
.. only:: Pro
.. _pro:
Pro
---
Pro stuff only
.. _troubleshooting:
Troubleshooting
---------------
Troubleshooting. See :ref:`features`
Attached sample project.
How to Reproduce
$ make latexpdf
Expected behavior
No response
Your project
sphinx.zip
Screenshots
No response
OS
Ubuntu 22.04
Python version
3.10.4
Sphinx version
5.0.2
Sphinx extensions
No response
Extra tools
No response
Additional context
No response
Thanks for report, smaller example:
Welcome to sample's documentation!
==================================
Features
--------
See: :ref:`troubleshooting`
.. only:: html
HTML
----
HTML stuff only
.. _troubleshooting:
Troubleshooting
---------------
Troubleshooting.
and make html
.
It is is actually documented:
This directive is designed to control only content of document. It could not control sections, labels and so on.
But the warning could be better I imagine.
The label is not under the directive. It's just after it. Anyway, is there a workaround?
The problem is with presence of a sectioning title underscope of only
, but the error message does not indicate it clearly. I don't know offhand a workaround for what you want but perhaps some advice will come here later hopefully.
If the only
directive contains any sections, it appends an only
node to the sibling of the current node. And it confuses the label system of Sphinx. Actually, the "troubleshooting" name is assigned to both <only>
and <section>
nodes:
<section ids="welcome-to-project-s-documentation" names="welcome\ to\ project's\ documentation!">
<title>
Welcome to project’s documentation!
<section ids="section" names="section">
<title>
section
<paragraph>
See:
<inline classes="xref std std-ref">
troubleshooting
<target refid="troubleshooting">
<only expr="Pro" ids="troubleshooting" names="troubleshooting">
<target refid="pro">
<section dupnames="pro" ids="pro id1" names="pro">
<title>
Pro
<paragraph>
Pro stuff only
<section dupnames="troubleshooting" ids="id2">
<title>
Troubleshooting
<paragraph>
Troubleshooting.
I think there is no workaround to avoid this behavior. This is one of the limitations of the only
directive.
Sidenote: If the only
directive contains no sections, it appends an only
node to the current node. And it will go well.
<section ids="welcome-to-project-s-documentation" names="welcome\ to\ project's\ documentation!">
<title>
Welcome to project’s documentation!
<section ids="section" names="section">
<title>
section
<paragraph>
See:
<reference internal="True" refid="troubleshooting">
<inline classes="std std-ref">
Troubleshooting
<only expr="Pro">
<target refid="pro">
<paragraph ids="pro" names="pro">
Pro stuff only
<target refid="troubleshooting">
<section dupnames="troubleshooting" ids="troubleshooting id1" names="troubleshooting">
<title>
Troubleshooting
<paragraph>
Troubleshooting.