Hi, The argument of `:ref:` role is a "target name" defined by :name: option. So the second one can't be referred. But you can refer the first one by giving explicit title to the `:ref:` role (ex. :ref:`link title <foo>`).
On the other hand, "numfig" feature assigns numbers only for the code-blocks having caption. So only third one can be referred by `:numref:` role. It would be nice if you post a PR to make our docs better. I'm not good at English, so it's very helpful :-) Thanks, Takeshi KOMIYA 2020年6月4日(木) 16:23 Stefano David <[email protected]>: > > Hi Takeshi, > > On Wednesday, 3 June 2020 17:21:34 UTC+2, Komiya Takeshi wrote: > Hi, > > At present, Sphinx assigns numbers to code-blocks having a caption. So > this is intended behavior. > > >If true, figures, tables and code-blocks are automatically numbered if they > >have a caption. The numref role is enabled. Obeyed so far only by HTML and > >LaTeX builders. Default is False. > >https://www.sphinx-doc.org/en/master/usage/configuration.html?highlight=numref#confval-numfig > Thank you for your answer! Given your explanation, it is now clear to me that > :caption: produces a caption and a number associated to the listing, while > :name: allows to crossreference the listing. > > However, I think that the documentation is IMHO misleading, because it does > not make clear that both :name: and :caption: need to be used. Also the > description of option :name: [1] is misleading, when it states "Define > implicit target name that can be referenced by using ref.", because both > :name: and :caption: need to be defined (although in the example there, both > are defined). > > To be more clear: given the example below, I expected at least two cross > references being generated (bar and baz), but only the third (baz) is > generated, although also the second has :caption: defined. However, correctly > sphinx creates only one. > > *************** > See :numref:`foo`, :numref:`bar`, and :numref:`baz`. > > .. code-block:: python > :name: foo > > def foo(): > return None > > > .. code-block:: python > :caption: bar > > def foo(): > return None > > > .. code-block:: python > :caption: baz > :name: baz > > def foo(): > return None > > See :ref:`foo`, :ref:`bar`, and :ref:`baz`. > > > End of file. > > > *************** > > > Thank you, > Stefnao > > > [1] > https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block > > -- > You received this message because you are subscribed to the Google Groups > "sphinx-users" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to [email protected]. > To view this discussion on the web visit > https://groups.google.com/d/msgid/sphinx-users/cb571368-45e3-4187-8b8f-087dfa36e75a%40googlegroups.com. -- You received this message because you are subscribed to the Google Groups "sphinx-users" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/CAFmkQANu4kM4gq901xgSN4weWyxqmStNy4aSnbYFQvNgUrrRGw%40mail.gmail.com.
