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.