In docs, use intersphinx to link to Python documentation

jdufresne · jdufresne · commit 7ce471e238cd · 2018-11-01T18:12:14.000-07:00
The intersphinx extension can generate automatic links to the documentation of objects in other projects. For complete details on intersphinx, see: http://www.sphinx-doc.org/en/master/ext/intersphinx.html
diff --git a/Doc/bytes_mode.rst b/Doc/bytes_mode.rst
@@ -93,12 +93,11 @@ to be given as well.
 Porting recommendations
 -----------------------
 
-Since end of life of Python 2 is coming in a few years,
-projects are strongly urged to make their code compatible with Python 3.
-General instructions for this are provided `in Python documentation`_ and in
-the `Conservative porting guide`_.
+Since end of life of Python 2 is coming in a few years, projects are strongly
+urged to make their code compatible with Python 3. General instructions for
+this are provided :ref:`in Python documentation <pyporting-howto>` and in the
+`Conservative porting guide`_.
 
-.. _in Python documentation: https://docs.python.org/3/howto/pyporting.html
 .. _Conservative porting guide: https://portingguide.readthedocs.io/en/latest/
 
 
diff --git a/Doc/conf.py b/Doc/conf.py
@@ -31,7 +31,10 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc']
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+]
 
 try:
     import sphinxcontrib.spelling
@@ -148,3 +151,5 @@
 
 # If false, no module index is generated.
 latex_use_modindex = True
+
+intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
diff --git a/Doc/installing.rst b/Doc/installing.rst
@@ -99,10 +99,8 @@ From a source repository::
 If you have more than one Python interpreter installed locally, you should
 use the same one you plan to use python-ldap with.
 
-Further instructions can be found in `Setuptools documentation`_.
-
-
-.. _Setuptools documentation: https://docs.python.org/3/distributing/index.html
+Further instructions can be found in :ref:`Setuptools documentation
+<distributing-index>`.
 
 
 .. _build prerequisites:
@@ -169,11 +167,10 @@ Packages for building and testing::
 setup.cfg
 =========
 
-The file setup.cfg allows to set some build and installation
-parameters for reflecting the local installation of required
-software packages. Only section ``[_ldap]`` is described here.
-More information about other sections can be found in
-`Setuptools documentation`_.
+The file setup.cfg allows to set some build and installation parameters for
+reflecting the local installation of required software packages. Only section
+``[_ldap]`` is described here. More information about other sections can be
+found in :ref:`Setuptools documentation <distributing-index>`.
 
 .. data:: library_dirs
 
diff --git a/Doc/sample_workflow.rst b/Doc/sample_workflow.rst
@@ -26,15 +26,14 @@ Clone the repository::
     $ git clone https://github.com/python-ldap/python-ldap
     $ cd python-ldap
 
-Create a `virtual environment`_ to ensure you in-development python-ldap won't
-affect the rest of your system::
+Create a :mod:`virtual environment <venv>` to ensure you in-development
+python-ldap won't affect the rest of your system::
 
     $ python3 -m venv __venv__
 
 (For Python 2, install `virtualenv`_ and use it instead of ``python3 -m venv``.)
 
 .. _git: https://git-scm.com/
-.. _virtual environment: https://docs.python.org/3/library/venv.html
 .. _virtualenv: https://virtualenv.pypa.io/en/stable/
 
 Activate the virtual environment::
