Fix #2916: numref role can also refer caption as an its linktext

doc/config.rst

@@ -295,14 +295,18 @@ General configuration
 .. confval:: numfig_format
 
    A dictionary mapping ``'figure'``, ``'table'``, ``'code-block'`` and
-   ``'section'`` to strings that are used for format of figure numbers.  Default
-   is to use ``'Fig. %s'`` for ``'figure'``, ``'Table %s'`` for ``'table'``,
-   ``'Listing %s'`` for ``'code-block'`` and ``'Section'`` for ``'section'``.
+   ``'section'`` to strings that are used for format of figure numbers.
+   As a special character, `%s` and `{number}` will be replaced to figure
+   number.  `{name}` will be replaced to figure caption.
+
+   Default is to use ``'Fig. %s'`` for ``'figure'``, ``'Table %s'`` for
+   ``'table'``, ``'Listing %s'`` for ``'code-block'`` and ``'Section'`` for
+   ``'section'``.
 
    .. versionadded:: 1.3
 
    .. versionchanged:: 1.5
-      Support format of section
+      Support format of section. Allow to refer the caption of figures.
 
 .. confval:: numfig_secnum_depth
 

doc/markup/inline.rst

@@ -213,7 +213,7 @@ Cross-referencing figures by figure number
 .. versionadded:: 1.3
 
 .. versionchanged:: 1.5
-   `numref` role can also refer sections
+   `numref` role can also refer sections.
 
 .. rst:role:: numref
 
@@ -223,7 +223,7 @@ Cross-referencing figures by figure number
 
    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.
+   The format of link text is same as :confval:`numfig_format`.
 
    If :confval:`numfig` is ``False``, figures are not numbered.
    so this role inserts not a reference but labels or link text.