From 83e8bbf58b196f18bb14ecf96a1519c5fd4a15b8 Mon Sep 17 00:00:00 2001
From: tk0miya <i.tkomiya@gmail.com>
Date: Thu, 9 Oct 2014 19:31:36 +0900
Subject: [PATCH] Add docs about :numref: role

---
 doc/markup/inline.rst | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/doc/markup/inline.rst b/doc/markup/inline.rst
index b5bb8d0c5..6f3ebe1c4 100644
--- a/doc/markup/inline.rst
+++ b/doc/markup/inline.rst
@@ -201,6 +201,24 @@ Referencing downloadable files
    suitable link generated to it.
 
 
+Cross-referencing figures by figure number
+------------------------------------------
+
+.. versionadded:: 1.3
+
+.. rst:role:: numref
+
+   Link to the specified figures, tables and code-blocks; the standard reST
+   labels are used. When you use this role, it will insert a reference to the
+   figure with link text by its figure number like "Fig. 1.1".
+
+   If an explicit link text is given (like usual: ``:doc:`Image of Sphinx (Fig.
+   #) <my-figure>```), the link caption will be the title of the reference.
+   As a special character, `#` will be replaced to figure number.
+
+   If :confval:`numfig` is ``False``, figures are not numbered.
+   so this role inserts not a reference but labels or link text.
+
 Cross-referencing other items of interest
 -----------------------------------------