Label after 'only' directive not found for xref

[josuegomes]

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.

sphinx.zip

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

[jfbu]

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.

[josuegomes]

The label is not under the directive. It's just after it. Anyway, is there a workaround?

[jfbu]

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.

[tk0miya]

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.