From 1367f6f9c62076cf3818c12d4be5cd43597c33fe Mon Sep 17 00:00:00 2001
From: Takayuki Shimizukawa <shimizukawa@gmail.com>
Date: Tue, 17 Dec 2013 23:54:30 +0900
Subject: [PATCH 1/2] Added a "Intersphinx" tutorial section.
 (:file:`doc/tutorial.rst`). Closes #1325

---
 CHANGES          |  5 +++++
 doc/tutorial.rst | 27 ++++++++++++++++++++++++++-
 2 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/CHANGES b/CHANGES
index a113c33a1..0cac254ca 100644
--- a/CHANGES
+++ b/CHANGES
@@ -1,6 +1,11 @@
 Release 1.2.1 (in development)
 ==============================
 
+Documentation
+-------------
+
+* #1325: Added a "Intersphinx" tutorial section. (:file:`doc/tutorial.rst`)
+
 
 Release 1.2 (released Dec 10, 2013)
 ===================================
diff --git a/doc/tutorial.rst b/doc/tutorial.rst
index 9fea11dbe..2dc69e18a 100644
--- a/doc/tutorial.rst
+++ b/doc/tutorial.rst
@@ -248,11 +248,36 @@ Therefore, you must add the appropriate path to :py:data:`sys.path` in your
 |more| See :mod:`sphinx.ext.autodoc` for the complete description of the
 features of autodoc.
 
+Intersphinx
+-----------
+
+Many sphinx documents including `Python reference document`_ are published on the internet. When you would like to make a link to such documents from your documentation, you can be done it with :mod:`sphinx.ext.intersphinx`.
+
+.. _Python reference document: http://docs.python.org/3
+
+In order to use intersphinx, you need to activate it in :file:`conf.py` by putting
+the string ``'sphinx.ext.intersphinx'`` into the list assigned to the
+:confval:`extensions` config value and setup :confval:`intersphinx_mapping`
+config value.
+
+For example, to link to ``io.open()`` in the python reference document,
+you need to setup your :confval:`intersphinx_mapping` like::
+
+   intersphinx_mapping = {'python': ('http://docs.python.org/3', None)}
+
+And now, you can write a cross-reference like: ``:py:func:`io.open```.
+The cross-reference that has no matching target in the current documentation
+set, it looks for targets in the documentation sets configured in
+:confval:`intersphinx_mapping`.
+
+|more| See :mod:`sphinx.ext.intersphinx` for the complete description of the
+features of intersphinx.
+
 
 More topics to be covered
 -------------------------
 
-- Other extensions (math, intersphinx, viewcode, doctest)
+- Other extensions (math, viewcode, doctest)
 - Static files
 - Selecting a theme
 - Templating

From bcff26c6dacbd2642517e43a80cdfeddd011aa6e Mon Sep 17 00:00:00 2001
From: Takayuki Shimizukawa <shimizukawa@gmail.com>
Date: Wed, 18 Dec 2013 08:33:37 +0900
Subject: [PATCH 2/2] update a Intersphinx tutorial section. refs #1325

---
 doc/tutorial.rst | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/doc/tutorial.rst b/doc/tutorial.rst
index 2dc69e18a..052317bc0 100644
--- a/doc/tutorial.rst
+++ b/doc/tutorial.rst
@@ -268,7 +268,9 @@ you need to setup your :confval:`intersphinx_mapping` like::
 And now, you can write a cross-reference like: ``:py:func:`io.open```.
 The cross-reference that has no matching target in the current documentation
 set, it looks for targets in the documentation sets configured in
-:confval:`intersphinx_mapping`.
+:confval:`intersphinx_mapping`. Intersphinx also works for some other
+:ref:`domains <domains>` roles including ``:ref:``, however it doesn't work
+for ``:doc:`` that is non-domain role.
 
 |more| See :mod:`sphinx.ext.intersphinx` for the complete description of the
 features of intersphinx.