Merge pull request #432 from tomschr/improve-intersphinx

tomschr · web-flow · commit c534e3fc15f9 · 2023-10-09T12:23:32.000+02:00
Improve external docs with intersphinx extension
diff --git a/changelog.d/432.doc.rst b/changelog.d/432.doc.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/migration/replace-deprecated-functions.rst b/docs/migration/replace-deprecated-functions.rst
@@ -8,17 +8,25 @@ Replacing Deprecated Functions
    the module level. The preferred way of using semver is through the
    :class:`~semver.version.Version` class.
 
-The deprecated functions can still be used in version 2.10.0 and above. However, in
-future versions of semver, the deprecated functions will be removed.
+The deprecated functions can still be used in version 2.10.0 and above.
+However, in future versions of semver, the deprecated functions will be removed.
 
-The following list shows the deprecated functions and how you can replace
+
+Deprecated Module Level Functions
+---------------------------------
+
+The following list shows the deprecated module level functions and how you can replace
 them with code which is compatible for future versions:
 
-* :func:`semver.bump_major`, :func:`semver.bump_minor`, :func:`semver.bump_patch`, :func:`semver.bump_prerelease`, :func:`semver.bump_build`
+* :func:`semver.bump_major <semver._deprecated.bump_major>`,
+  :func:`semver.bump_minor <semver._deprecated.bump_minor>`,
+  :func:`semver.bump_patch <semver._deprecated.bump_patch>`,
+  :func:`semver.bump_prerelease <semver._deprecated.bump_prerelease>`,
+  :func:`semver.bump_build <semver._deprecated.bump_build>`
 
   Replace them with the respective methods of the :class:`~semver.version.Version`
   class.
-  For example, the function :func:`semver.bump_major` is replaced by
+  For example, the function :func:`semver.bump_major <semver._deprecated.bump_major>` is replaced by
   :meth:`Version.bump_major <semver.version.Version.bump_major>` and calling the ``str(versionobject)``:
 
   .. code-block:: python
@@ -30,12 +38,7 @@ them with code which is compatible for future versions:
 
   Likewise with the other module level functions.
 
-* :meth:`semver.Version.isvalid`
-
-   Replace it with :meth:`Version.is_valid <semver.version.Version.is_valid>`:
-
-
-* :func:`semver.finalize_version`
+* :func:`semver.finalize_version <semver._deprecated.finalize_version>`
 
   Replace it with :meth:`Version.finalize_version <semver.version.Version.finalize_version>`:
 
@@ -46,7 +49,7 @@ them with code which is compatible for future versions:
      >>> s1 == s2
      True
 
-* :func:`semver.format_version`
+* :func:`semver.format_version <semver._deprecated.format_version>`
 
   Replace it with ``str(versionobject)``:
 
@@ -57,7 +60,7 @@ them with code which is compatible for future versions:
      >>> s1 == s2
      True
 
-* :func:`semver.max_ver`
+* :func:`semver.max_ver <semver._deprecated.max_ver>`
 
   Replace it with ``max(version1, version2, ...)`` or ``max([version1, version2, ...])`` and a ``key``:
 
@@ -68,7 +71,7 @@ them with code which is compatible for future versions:
      >>> s1 == s2
      True
 
-* :func:`semver.min_ver`
+* :func:`semver.min_ver <semver._deprecated.min_ver>`
 
   Replace it with ``min(version1, version2, ...)`` or ``min([version1, version2, ...])`` and a ``key``:
 
@@ -79,7 +82,7 @@ them with code which is compatible for future versions:
      >>> s1 == s2
      True
 
-* :func:`semver.parse`
+* :func:`semver.parse <semver._deprecated.parse>`
 
   Replace it with :meth:`Version.parse <semver.version.Version.parse>` and call
   :meth:`Version.to_dict <semver.version.Version.to_dict>`:
@@ -91,7 +94,7 @@ them with code which is compatible for future versions:
      >>> v1 == v2
      True
 
-* :func:`semver.parse_version_info`
+* :func:`semver.parse_version_info <semver._deprecated.parse_version_info>`
 
   Replace it with :meth:`Version.parse <semver.version.Version.parse>`:
 
@@ -102,7 +105,7 @@ them with code which is compatible for future versions:
      >>> v1 == v2
      True
 
-* :func:`semver.replace`
+* :func:`semver.replace <semver._deprecated.replace>`
 
   Replace it with :meth:`Version.replace <semver.version.Version.replace>`:
 
@@ -112,3 +115,22 @@ them with code which is compatible for future versions:
      >>> s2 = str(Version.parse('1.2.3').replace(major=2, patch=10))
      >>> s1 == s2
      True
+
+
+Deprected Version methods
+-------------------------
+
+The following list shows the deprecated methods of the :class:`~semver.version.Version` class.
+
+* :meth:`Version.isvalid <semver.version.Version.isvalid>`
+
+   Replace it with :meth:`Version.is_valid <semver.version.Version.is_valid>`:
+
+
+Deprecated Classes
+------------------
+
+* :class:`VersionInfo <semver.version.VersionInfo>`
+
+   The class was renamed to :class:`~semver.version.Version`.
+   Don't use the old name anymore.
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.
@@ -87,12 +87,12 @@ Depending on your use case, the following methods are available:
 
 * From a string into a dictionary
 
-  To access individual parts, you can use the function :func:`semver.parse`::
+  To access individual parts, you can use the function :func:`~semver._deprecated.parse`::
 
     >>> 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`	`+`