Numref strange behaviour

[Stefano David]

Hi,


I am not sure if the behaviour of the numref role has changed in recent times; I refer to this old issue by jfbu: https://github.com/sphinx-doc/sphinx/issues/3012
In Sphinx v3.0.3, the snippet in the issue does not not compile as expected, because there is no :name: attached to the code-block. So far so good, given the explanation in the issue.



However, to my wonder, that code does not compile even if I replace :content: foo with :name: foo! It is necessary to add both :caption: AND :name: to code-block, for numref to work (they can have different values, by the way).


With examples:

***** code 1 *****

.. code-block:: python

   :name: foo

      def foo():

          return None

***** code 2 *****

.. code-block:: python

   :name: foo

   :caption: foo bar

      def foo():

          return None

*****

Code 1 shows a warning and does not create a reference, while code 2 works. Is this the correct behaviour and I am missing something, or is it a bug? In the first case, then the documentation at [1] (which is the same text as mentioned by Jean Francois [2]) is misleading or wrong, in the second case I would open an issue.

Cheers,
Stefano

[1] https://www.sphinx-doc.org/en/stable/usage/restructuredtext/directives.html#showing-code-examples

[2] https://www.sphinx-doc.org/en/1.4/markup/code.html

[Komiya Takeshi]

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

Thanks,
Takeshi KOMIYA

2020年5月24日(日) 20:38 Stefano David <ste...@gmail.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 sphinx-users...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/5494546c-180f-43ae-af90-2e91a474ab01%40googlegroups.com.

[Stefano David]

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

[Komiya Takeshi]

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 <ste...@gmail.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 sphinx-users...@googlegroups.com.

> To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/cb571368-45e3-4187-8b8f-087dfa36e75a%40googlegroups.com.

[Stefano David]

Hi Takeshi,

On Thursday, 4 June 2020 16:01:19 UTC+2, Komiya Takeshi wrote:

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 :-)

I just opened a PR, by taking into account what you explained. I hope I did it all the right way :-)

Best regards,

Stefano

[root]