diff --git a/changelog.d/432.doc.rst b/changelog.d/432.doc.rst new file mode 100644 index 00000000..ab09b96c --- /dev/null +++ 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 index 840ddbd4..3236c2a2 100644 --- 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 index 2d40635d..75579d0f 100644 --- 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__ `, :py:meth:`__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 index eab3248d..39d8cb4b 100644 --- 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 new file mode 100644 index 00000000..455215a7 Binary files /dev/null and b/docs/inventories/pydantic.inv differ diff --git a/docs/inventories/python-objects.inv b/docs/inventories/python-objects.inv index 6f01e284..90bfa0a6 100644 Binary files a/docs/inventories/python-objects.inv and b/docs/inventories/python-objects.inv differ diff --git a/docs/migration/replace-deprecated-functions.rst b/docs/migration/replace-deprecated-functions.rst index 2fe1bb2d..c0091b73 100644 --- 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 `, + :func:`semver.bump_minor `, + :func:`semver.bump_patch `, + :func:`semver.bump_prerelease `, + :func:`semver.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 ` is replaced by :meth:`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 `: - - -* :func:`semver.finalize_version` +* :func:`semver.finalize_version ` Replace it with :meth:`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 ` 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 ` 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 ` 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 ` Replace it with :meth:`Version.parse ` and call :meth:`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 ` Replace it with :meth:`Version.parse `: @@ -102,7 +105,7 @@ them with code which is compatible for future versions: >>> v1 == v2 True -* :func:`semver.replace` +* :func:`semver.replace ` Replace it with :meth:`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 ` + + Replace it with :meth:`Version.is_valid `: + + +Deprecated Classes +------------------ + +* :class:`VersionInfo ` + + The class was renamed to :class:`~semver.version.Version`. + Don't use the old name anymore. \ No newline at end of file diff --git a/docs/usage/access-parts-of-a-version.rst b/docs/usage/access-parts-of-a-version.rst index 4eb9274f..b1ce3a14 100644 --- 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 index c3651a5e..4553056a 100644 --- 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 index ddd03b68..839ad68b 100644 --- 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 index b8dfdd83..9404ae4b 100644 --- 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 index a6eac5cc..f0c423f8 100644 --- 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. pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy