Improve external docs with intersphinx extension

tomschr · tomschr · commit c6068b39475e · 2023-10-09T11:49:00.000+02:00
* Downloads the inventories for Python and Pydantic
* Use the correct :ref: syntax ("INVENTORY_NAME:OBJECT")
diff --git a/changelog.d/432.trivial.rst b/changelog.d/432.trivial.rst
@@ -0,0 +1,2 @@
+Improve external doc links to Python and Pydantic.
+
diff --git a/docs/advanced/combine-pydantic-and-semver.rst b/docs/advanced/combine-pydantic-and-semver.rst
@@ -58,7 +58,7 @@ To work with Pydantic>2.0, use the following steps:
         ManifestVersion = Annotated[Version, _VersionPydanticAnnotation]
 
 2. Create a new model (in this example :class:`MyModel`) and derive
-   it from :class:`pydantic.BaseModel`:
+   it from :py:class:`pydantic:pydantic.BaseModel`:
 
     .. code-block:: python
 
@@ -76,4 +76,4 @@ To work with Pydantic>2.0, use the following steps:
    The attribute :py:attr:`model.version` will be an instance of
    :class:`~semver.version.Version`.
    If the version is invalid, the construction will raise a
-   :py:exc:`pydantic.ValidationError`.
+   :py:class:`pydantic:pydantic_core.ValidationError`.
diff --git a/docs/changelog-semver3-devel.rst b/docs/changelog-semver3-devel.rst
@@ -132,11 +132,11 @@ Improved Documentation
     :class:`~semver.version.Version` class
   * Remove semver. prefix in doctests to make examples shorter
   * Correct some references to dunder methods like
-    :func:`~.semver.version.Version.__getitem__`,
-    :func:`~.semver.version.Version.__gt__` etc.
+    :func:`~semver.version.Version.__getitem__`,
+    :func:`~semver.version.Version.__gt__` etc.
   * Remove inconsistencies and mention module level function as
     deprecated and discouraged from using
-  * Make empty :py:func:`super` call in :file:`semverwithvprefix.py` example
+  * Make empty :py:class:`python:super` call in :file:`semverwithvprefix.py` example
 
 * :gh:`315`: Improve release procedure text
 
@@ -151,34 +151,32 @@ Trivial/Internal Changes
 
   The following functions got renamed:
 
-  * function ``semver.version.comparator`` got renamed to
+  * function :func:`semver.version.comparator` got renamed to
     :func:`semver.version._comparator` as it is only useful
     inside the :class:`~semver.version.Version` class.
-  * function ``semver.version.cmp`` got renamed to
+  * function :func:`semver.version.cmp` got renamed to
     :func:`semver.version._cmp` as it is only useful
     inside the :class:`~semver.version.Version` class.
 
   The following functions got integrated into the
   :class:`~semver.version.Version` class:
 
-  * function ``semver.version._nat_cmd`` as a classmethod
-  * function ``semver.version.ensure_str``
+  * function :func:`semver.version._nat_cmd` as a classmethod
+  * function :func:`semver.version.ensure_str`
 
 * :gh:`313`: Correct :file:`tox.ini` for ``changelog`` entry to skip
   installation for semver. This should speed up the execution
   of towncrier.
 
 * :gh:`316`: Comparisons of :class:`~semver.version.Version` class and other
-  types return now a :py:const:`NotImplemented` constant instead
-  of a :py:exc:`TypeError` exception.
+  types return now a :py:data:`python:NotImplemented` constant instead
+  of a :py:exc:`python:TypeError` exception.
 
-  The `NotImplemented`_ section of the Python documentation recommends
-  returning this constant when comparing with ``__gt__``, ``__lt__``,
-  and other comparison operators to "to indicate that the operation is
+  In the Python documentation, :py:data:`python:NotImplemented` recommends
+  returning this constant when comparing with :py:meth:`__gt__ <python:object.__gt__>`, :py:meth:`__lt__ <python:object.__lt__>`,
+  and other comparison operators "to indicate that the operation is
   not implemented with respect to the other type".
 
-  .. _NotImplemented: https://docs.python.org/3/library/constants.html#NotImplemented
-
 * :gh:`319`: Introduce stages in :file:`.travis.yml`
   The config file contains now two stages: check and test. If
   check fails, the test stage won't be executed. This could
@@ -206,7 +204,7 @@ Version 3.0.0-dev.2
 Deprecations
 ------------
 
-* :gh:`169`: Deprecate CLI functions not imported from ``semver.cli``.
+* :gh:`169`: Deprecate CLI functions not imported from :mod:`semver.cli`.
 
 
 .. _semver-3.0.0-dev.2-features:
@@ -222,10 +220,10 @@ Features
   * Create :file:`src/semver/_deprecated.py` for the ``deprecated`` decorator and other deprecated functions
   * Create :file:`src/semver/__main__.py` to allow calling the CLI using :command:`python -m semver`
   * Create :file:`src/semver/_types.py` to hold type aliases
-  * Create :file:`src/semver/version.py` to hold the :class:`Version` class (old name :class:`VersionInfo`) and its utility functions
+  * Create :file:`src/semver/version.py` to hold the :class:`~semver.version.Version` class (old name :class:`~semver.version.VersionInfo`) and its utility functions
   * Create :file:`src/semver/__about__.py` for all the metadata variables
 
-* :gh:`305`: Rename :class:`VersionInfo` to :class:`Version` but keep an alias for compatibility
+* :gh:`305`: Rename :class:`~semver.version.VersionInfo` to :class:`~semver.version.Version` but keep an alias for compatibility
 
 
 .. _semver-3.0.0-dev.2-docs:
@@ -239,7 +237,7 @@ Improved Documentation
   * Add migration chapter from semver2 to semver3.
   * Distinguish between changlog for version 2 and 3
 
-* :gh:`305`: Add note about :class:`Version` rename.
+* :gh:`305`: Add note about :class:`~semver.version.Version` rename.
 
 
 .. _semver-3.0.0-dev.2-trivial:
@@ -314,8 +312,8 @@ Features
   * Split test suite into separate files under :file:`tests/`
     directory
   * Adjust and update :file:`setup.py`. Requires Python >=3.6.*
-    Extract metadata directly from source (affects all the ``__version__``,
-    ``__author__`` etc. variables)
+    Extract metadata directly from source (affects all the :data:`~semver.__about__.__version__`,
+    :data:`~semver.__about__.__author__` etc. variables)
 
 * :gh:`270`: Configure Towncrier (:pr:`273`:)
 
@@ -331,7 +329,7 @@ Features
   * Update documentation and add include a new section
     "Changelog" included from :file:`changelog.d/README.rst`.
 
-* :gh:`276`: Document how to create a sublass from :class:`VersionInfo` class
+* :gh:`276`: Document how to create a sublass from :class:`~semver.version.VersionInfo` class
 
 * :gh:`213`: Add typing information
 
diff --git a/docs/conf.py b/docs/conf.py
@@ -126,8 +126,13 @@ def find_version(*file_paths):
 # See https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
 intersphinx_mapping = {
     # Download it from the root with:
-    # wget -O docs/python-objects.inv https://docs.python.org/3/objects.inv
+    # wget -O docs/inventories/python-objects.inv https://docs.python.org/3/objects.inv
     "python": ("https://docs.python.org/3", (None, "inventories/python-objects.inv")),
+    # wget -O docs/inventories/pydantic.inv https://docs.pydantic.dev/latest/objects.inv
+    "pydantic": (
+        "https://docs.pydantic.dev/latest/",
+        (None, "inventories/pydantic.inv"),
+    ),
 }
 # Avoid side-effects (namely that documentations local references can
 # suddenly resolve to an external location.)
diff --git a/docs/inventories/pydantic.inv b/docs/inventories/pydantic.inv
diff --git a/docs/inventories/python-objects.inv b/docs/inventories/python-objects.inv
diff --git a/docs/usage/access-parts-of-a-version.rst b/docs/usage/access-parts-of-a-version.rst
@@ -21,7 +21,7 @@ parts of a version:
     'build.4'
 
 However, the attributes are read-only. You cannot change any of the above attributes.
-If you do, you get an :py:exc:`AttributeError`::
+If you do, you get an :py:exc:`python:AttributeError`::
 
     >>> v.minor = 5
     Traceback (most recent call last):
diff --git a/docs/usage/access-parts-through-index.rst b/docs/usage/access-parts-through-index.rst
@@ -33,7 +33,7 @@ Or, as an alternative, you can pass a :func:`slice` object:
     >>> ver[sl]
     (10, 3, 2)
 
-Negative numbers or undefined parts raise an :py:exc:`IndexError` exception:
+Negative numbers or undefined parts raise an :py:exc:`python:IndexError` exception:
 
 .. code-block:: python
 
diff --git a/docs/usage/compare-versions.rst b/docs/usage/compare-versions.rst
@@ -62,7 +62,7 @@ To compare two versions depends on your type:
     >>> "3.5.0" > v
     True
 
-  However, if you compare incomplete strings, you get a :py:exc:`ValueError` exception::
+  However, if you compare incomplete strings, you get a :py:exc:`python:ValueError` exception::
 
     >>> v > "1.0"
     Traceback (most recent call last):
@@ -82,7 +82,7 @@ To compare two versions depends on your type:
    >>> dict(major=1) < v
    True
 
-  If the dictionary contains unknown keys, you get a :py:exc:`TypeError` exception::
+  If the dictionary contains unknown keys, you get a :py:exc:`python:TypeError` exception::
 
     >>> v > dict(major=1, unknown=42)
     Traceback (most recent call last):
diff --git a/docs/usage/create-a-version.rst b/docs/usage/create-a-version.rst
@@ -41,7 +41,7 @@ A :class:`~semver.version.Version` instance can be created in different ways:
     Version(major=3, minor=4, patch=5, prerelease='pre.2', build='build.4')
 
   Keep in mind, the ``major``, ``minor``, ``patch`` parts has to
-  be positive integers or strings:
+  be positive integers or strings, otherwise a :py:exc:`python:ValueError` is raised:
 
       >>> d = {'major': -3, 'minor': 4, 'patch': 5,  'prerelease': 'pre.2', 'build': 'build.4'}
       >>> Version(**d)
@@ -50,7 +50,7 @@ A :class:`~semver.version.Version` instance can be created in different ways:
       ValueError: 'major' is negative. A version can only be positive.
 
   As a minimum requirement, your dictionary needs at least the ``major``
-  key, others can be omitted. You get a ``TypeError`` if your
+  key, others can be omitted. You get a :py:exc:`python:TypeError` if your
   dictionary contains invalid keys.
   Only the keys ``major``, ``minor``, ``patch``, ``prerelease``, and ``build``
   are allowed.
@@ -92,7 +92,7 @@ Depending on your use case, the following methods are available:
     >>> semver.parse("3.4.5-pre.2+build.4")
     {'major': 3, 'minor': 4, 'patch': 5, 'prerelease': 'pre.2', 'build': 'build.4'}
 
-  If you pass an invalid version string you will get a :py:exc:`ValueError`::
+  If you pass an invalid version string you will get a :py:exc:`python:ValueError`::
 
     >>> semver.parse("1.2")
     Traceback (most recent call last):
diff --git a/docs/version-policy.rst b/docs/version-policy.rst
@@ -30,7 +30,9 @@ semver Version 3
 
 We will not intentionally make breaking changes in minor releases of V3.
 
-Methods marked as ``deprecated`` raise a warning message when used from the :py:mod:`warnings` module.
+Methods marked as ``deprecated`` raise a warning message when used from the
+:py:mod:`python:warnings` module.
+Refer to section :ref:`sec_display_deprecation_warnings` to get more information about how to customize it.
 Check section :ref:`sec_replace_deprecated_functions` to make your code
 ready for future major releases.
 

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+Improve external doc links to Python and Pydantic.`
	`2`	`+`