Use intersphinx for links to pip and Nox docs (cjolowicz#267)

* docs: Add intersphinx extension

* docs: Provide intersphinx mapping for Nox

* docs(sessions): Use intersphinx for links to Nox documentation

* docs: Add intersphinx mapping for pip

* chore: Configure flake8-rst-docstrings to recognize :ref: role

* docs(sessions): Use intersphinx for links to pip documentation

.flake8

@@ -5,5 +5,5 @@ max-line-length = 80
 max-complexity = 10
 docstring-convention = google
 per-file-ignores = tests/*:S101
-rst-roles = const,class,func,meth,mod
+rst-roles = const,class,func,meth,mod,ref
 rst-directives = deprecated

docs/conf.py

@@ -7,9 +7,14 @@
 copyright = f"{datetime.now().year}, {author}"
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
 ]
 autodoc_typehints = "description"
 html_theme = "furo"
 html_favicon = "images/favicon.png"
 html_logo = "images/logo.png"
+intersphinx_mapping = {
+    "nox": ("https://nox.thea.codes/en/stable", None),
+    "pip": ("https://pip.pypa.io/en/stable", None),
+}

src/nox_poetry/sessions.py

@@ -15,14 +15,11 @@
 
 
 def session(*args: Any, **kwargs: Any) -> Any:
-    """Drop-in replacement for the nox.session_ decorator.
+    """Drop-in replacement for the :func:`nox.session` decorator.
 
     Use this decorator instead of ``@nox.session``. Session functions are passed
-    :class:`Session` instead of ``nox.Session``; otherwise, the decorators work
-    exactly the same.
-
-    .. _nox.session:
-        https://nox.thea.codes/en/stable/config.html#nox.session
+    :class:`Session` instead of :class:`nox.sessions.Session`; otherwise, the
+    decorators work exactly the same.
 
     Args:
         args: Positional arguments are forwarded to ``nox.session``.
@@ -67,31 +64,24 @@ def install(self, *args: str, **kwargs: Any) -> None:
         """Install packages into a Nox session using Poetry.
 
         This function installs packages into the session's virtual environment. It
-        is a wrapper for `nox.sessions.Session.install`_, whose positional
-        arguments are command-line arguments for `pip install`_, and whose keyword
-        arguments are the same as those for `nox.sessions.Session.run`_.
+        is a wrapper for :meth:`nox.sessions.Session.install`, whose positional
+        arguments are command-line arguments for :ref:`pip install`, and whose keyword
+        arguments are the same as those for :meth:`nox.sessions.Session.run`.
 
         If a positional argument is ".", a wheel is built using
         :meth:`build_package`, and the argument is replaced with the file URL
         returned by that function. Otherwise, the argument is forwarded unchanged.
 
-        In addition, a `constraints file`_ is generated for the package
-        dependencies using :meth:`export_requirements`, and passed to ``pip
-        install`` via its ``--constraint`` option. This ensures that any package
-        installed will be at the version specified in Poetry's lock file.
-
-        .. _pip install: https://pip.pypa.io/en/stable/reference/pip_install/
-        .. _nox.sessions.Session.install:
-            https://nox.thea.codes/en/stable/config.html#nox.sessions.Session.install
-        .. _nox.sessions.Session.run:
-            https://nox.thea.codes/en/stable/config.html#nox.sessions.Session.run
-        .. _constraints file:
-            https://pip.pypa.io/en/stable/user_guide/#constraints-files
+        In addition, a :ref:`constraints file <Constraints Files>` is generated
+        for the package dependencies using :meth:`export_requirements`, and
+        passed to ``pip install`` via its ``--constraint`` option. This ensures
+        that any package installed will be at the version specified in Poetry's
+        lock file.
 
         Args:
             args: Command-line arguments for ``pip install``.
             kwargs: Keyword-arguments for ``session.install``. These are the same
-                as those for `nox.sessions.Session.run`_.
+                as those for :meth:`nox.sessions.Session.run`.
         """
         from nox_poetry.core import Session_install
 
@@ -128,10 +118,11 @@ def installroot(
         This function installs the package located in the current directory into the
         session's virtual environment.
 
-        A constraints file is generated for the package dependencies using
-        :meth:`export_requirements`, and passed to ``pip install`` via its
-        ``--constraint`` option. This ensures that core dependencies are installed
-        using the versions specified in Poetry's lock file.
+        A :ref:`constraints file <Constraints Files>` is generated for the
+        package dependencies using :meth:`export_requirements`, and passed to
+        :ref:`pip install` via its ``--constraint`` option. This ensures that
+        core dependencies are installed using the versions specified in Poetry's
+        lock file.
 
         Args:
             distribution_format: The distribution format, either wheel or sdist.
@@ -155,18 +146,16 @@ def installroot(
     def export_requirements(self) -> Path:
         """Export a requirements file from Poetry.
 
-        This function uses `poetry export`_ to generate a `requirements file`_
-        containing the project dependencies at the versions specified in
-        ``poetry.lock``. The requirements file includes both core and development
-        dependencies.
+        This function uses `poetry export`_ to generate a :ref:`requirements
+        file <Requirements Files>` containing the project dependencies at the
+        versions specified in ``poetry.lock``. The requirements file includes
+        both core and development dependencies.
 
         The requirements file is stored in a per-session temporary directory,
         together with a hash digest over ``poetry.lock`` to avoid generating the
         file when the dependencies have not changed since the last run.
 
         .. _poetry export: https://python-poetry.org/docs/cli/#export
-        .. _requirements file:
-            https://pip.pypa.io/en/stable/user_guide/#requirements-files
 
         Returns:
             The path to the requirements file.
@@ -211,7 +200,7 @@ def build_package(
 
 
 class _SessionProxy:
-    """Proxy for nox.Session."""
+    """Proxy for :class:`nox.sessions.Session`."""
 
     def __init__(self, session: nox.Session) -> None:
         """Initialize."""
@@ -223,10 +212,7 @@ def __getattr__(self, name: str) -> Any:
 
 
 class Session(_SessionProxy):
-    """Proxy for nox.sessions.Session_, passed to user-defined session functions.
-
-    .. _nox.sessions.Session:
-        https://nox.thea.codes/en/stable/config.html#nox.sessions.Session
+    """Proxy for :class:`nox.sessions.Session`, passed to session functions.
 
     This class overrides :meth:`session.install
     <nox_poetry.sessions._PoetrySession.install>`, and provides Poetry-related