numrefs and figures

[Warren Block]

Looking at
http://www.sphinx-doc.org/en/stable/markup/inline.html#role-numref

It says:

If an explicit link text is given (like usual: :numref:`Image of
Sphinx (Fig. %s) <my-figure>`), the link caption will be the title of
the reference. As a special character, %s will be replaced to figure
number.

That first sentence is not clear at all. The "link caption"... is that
the link, or the thing we are linking to? "Will be" is also unclear.
Is set to? Is read from?

Right now, I am using a lot of numrefs to figures. Figures do not,
apparently have a title, but do have a caption. What I would like to do
is have both the caption and the figure number in my text. For example:

:numref:`Figure %s <example_fig>` talks about badgers.

.. _example_fig:

.. figure:: badger.jpg

The Noble Badger

When rendered, the text shows just:

Figure 1.1 talks about badgers.

If it works the other way around, that would be all right, too:

:numref:`Figure %s, The Noble Badger <example_fig>` talks about
badgers.

.. _example_fig:

.. figure:: badger.jpg


No caption on the figure, but when rendered it would show "Figure 1.1,
The Noble Badger" in the figure. Except it doesn't, which led me to the
baffling explanation of numref above.

I'm using Sphinx 1.4.4, with

extensions = [
'sphinx.ext.ifconfig',
'sphinxcontrib.httpdomain'
]
numfig = True
numfig_secnum_depth = (2)


Thanks!