Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit c534e3f

Browse filesBrowse files
tomschrtomschr
authored
Merge pull request #432 from tomschr/improve-intersphinx
Improve external docs with intersphinx extension
2 parents 9a98394 + 23e0e73 commit c534e3f
Copy full SHA for c534e3f

12 files changed

+79
-50
lines changed

‎changelog.d/432.doc.rst

Copy file name to clipboard
+2Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Improve external doc links to Python and Pydantic.
2+

‎docs/advanced/combine-pydantic-and-semver.rst

Copy file name to clipboardExpand all lines: docs/advanced/combine-pydantic-and-semver.rst
+2-2Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ To work with Pydantic>2.0, use the following steps:
5858
ManifestVersion = Annotated[Version, _VersionPydanticAnnotation]
5959
6060
2. Create a new model (in this example :class:`MyModel`) and derive
61-
it from :class:`pydantic.BaseModel`:
61+
it from :py:class:`pydantic:pydantic.BaseModel`:
6262

6363
.. code-block:: python
6464
@@ -76,4 +76,4 @@ To work with Pydantic>2.0, use the following steps:
7676
The attribute :py:attr:`model.version` will be an instance of
7777
:class:`~semver.version.Version`.
7878
If the version is invalid, the construction will raise a
79-
:py:exc:`pydantic.ValidationError`.
79+
:py:class:`pydantic:pydantic_core.ValidationError`.

‎docs/changelog-semver3-devel.rst

Copy file name to clipboardExpand all lines: docs/changelog-semver3-devel.rst
+19-21Lines changed: 19 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -132,11 +132,11 @@ Improved Documentation
132132
:class:`~semver.version.Version` class
133133
* Remove semver. prefix in doctests to make examples shorter
134134
* Correct some references to dunder methods like
135-
:func:`~.semver.version.Version.__getitem__`,
136-
:func:`~.semver.version.Version.__gt__` etc.
135+
:func:`~semver.version.Version.__getitem__`,
136+
:func:`~semver.version.Version.__gt__` etc.
137137
* Remove inconsistencies and mention module level function as
138138
deprecated and discouraged from using
139-
* Make empty :py:func:`super` call in :file:`semverwithvprefix.py` example
139+
* Make empty :py:class:`python:super` call in :file:`semverwithvprefix.py` example
140140

141141
* :gh:`315`: Improve release procedure text
142142

@@ -151,34 +151,32 @@ Trivial/Internal Changes
151151

152152
The following functions got renamed:
153153

154-
* function ``semver.version.comparator`` got renamed to
154+
* function :func:`semver.version.comparator` got renamed to
155155
:func:`semver.version._comparator` as it is only useful
156156
inside the :class:`~semver.version.Version` class.
157-
* function ``semver.version.cmp`` got renamed to
157+
* function :func:`semver.version.cmp` got renamed to
158158
:func:`semver.version._cmp` as it is only useful
159159
inside the :class:`~semver.version.Version` class.
160160

161161
The following functions got integrated into the
162162
:class:`~semver.version.Version` class:
163163

164-
* function ``semver.version._nat_cmd`` as a classmethod
165-
* function ``semver.version.ensure_str``
164+
* function :func:`semver.version._nat_cmd` as a classmethod
165+
* function :func:`semver.version.ensure_str`
166166

167167
* :gh:`313`: Correct :file:`tox.ini` for ``changelog`` entry to skip
168168
installation for semver. This should speed up the execution
169169
of towncrier.
170170

171171
* :gh:`316`: Comparisons of :class:`~semver.version.Version` class and other
172-
types return now a :py:const:`NotImplemented` constant instead
173-
of a :py:exc:`TypeError` exception.
172+
types return now a :py:data:`python:NotImplemented` constant instead
173+
of a :py:exc:`python:TypeError` exception.
174174

175-
The `NotImplemented`_ section of the Python documentation recommends
176-
returning this constant when comparing with ``__gt__``, ``__lt__``,
177-
and other comparison operators to "to indicate that the operation is
175+
In the Python documentation, :py:data:`python:NotImplemented` recommends
176+
returning this constant when comparing with :py:meth:`__gt__ <python:object.__gt__>`, :py:meth:`__lt__ <python:object.__lt__>`,
177+
and other comparison operators "to indicate that the operation is
178178
not implemented with respect to the other type".
179179

180-
.. _NotImplemented: https://docs.python.org/3/library/constants.html#NotImplemented
181-
182180
* :gh:`319`: Introduce stages in :file:`.travis.yml`
183181
The config file contains now two stages: check and test. If
184182
check fails, the test stage won't be executed. This could
@@ -206,7 +204,7 @@ Version 3.0.0-dev.2
206204
Deprecations
207205
------------
208206

209-
* :gh:`169`: Deprecate CLI functions not imported from ``semver.cli``.
207+
* :gh:`169`: Deprecate CLI functions not imported from :mod:`semver.cli`.
210208

211209

212210
.. _semver-3.0.0-dev.2-features:
@@ -222,10 +220,10 @@ Features
222220
* Create :file:`src/semver/_deprecated.py` for the ``deprecated`` decorator and other deprecated functions
223221
* Create :file:`src/semver/__main__.py` to allow calling the CLI using :command:`python -m semver`
224222
* Create :file:`src/semver/_types.py` to hold type aliases
225-
* Create :file:`src/semver/version.py` to hold the :class:`Version` class (old name :class:`VersionInfo`) and its utility functions
223+
* Create :file:`src/semver/version.py` to hold the :class:`~semver.version.Version` class (old name :class:`~semver.version.VersionInfo`) and its utility functions
226224
* Create :file:`src/semver/__about__.py` for all the metadata variables
227225

228-
* :gh:`305`: Rename :class:`VersionInfo` to :class:`Version` but keep an alias for compatibility
226+
* :gh:`305`: Rename :class:`~semver.version.VersionInfo` to :class:`~semver.version.Version` but keep an alias for compatibility
229227

230228

231229
.. _semver-3.0.0-dev.2-docs:
@@ -239,7 +237,7 @@ Improved Documentation
239237
* Add migration chapter from semver2 to semver3.
240238
* Distinguish between changlog for version 2 and 3
241239

242-
* :gh:`305`: Add note about :class:`Version` rename.
240+
* :gh:`305`: Add note about :class:`~semver.version.Version` rename.
243241

244242

245243
.. _semver-3.0.0-dev.2-trivial:
@@ -314,8 +312,8 @@ Features
314312
* Split test suite into separate files under :file:`tests/`
315313
directory
316314
* Adjust and update :file:`setup.py`. Requires Python >=3.6.*
317-
Extract metadata directly from source (affects all the ``__version__``,
318-
``__author__`` etc. variables)
315+
Extract metadata directly from source (affects all the :data:`~semver.__about__.__version__`,
316+
:data:`~semver.__about__.__author__` etc. variables)
319317

320318
* :gh:`270`: Configure Towncrier (:pr:`273`:)
321319

@@ -331,7 +329,7 @@ Features
331329
* Update documentation and add include a new section
332330
"Changelog" included from :file:`changelog.d/README.rst`.
333331

334-
* :gh:`276`: Document how to create a sublass from :class:`VersionInfo` class
332+
* :gh:`276`: Document how to create a sublass from :class:`~semver.version.VersionInfo` class
335333

336334
* :gh:`213`: Add typing information
337335

‎docs/conf.py

Copy file name to clipboardExpand all lines: docs/conf.py
+6-1Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -126,8 +126,13 @@ def find_version(*file_paths):
126126
# See https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
127127
intersphinx_mapping = {
128128
# Download it from the root with:
129-
# wget -O docs/python-objects.inv https://docs.python.org/3/objects.inv
129+
# wget -O docs/inventories/python-objects.inv https://docs.python.org/3/objects.inv
130130
"python": ("https://docs.python.org/3", (None, "inventories/python-objects.inv")),
131+
# wget -O docs/inventories/pydantic.inv https://docs.pydantic.dev/latest/objects.inv
132+
"pydantic": (
133+
"https://docs.pydantic.dev/latest/",
134+
(None, "inventories/pydantic.inv"),
135+
),
131136
}
132137
# Avoid side-effects (namely that documentations local references can
133138
# suddenly resolve to an external location.)

‎docs/inventories/pydantic.inv

Copy file name to clipboard
3.98 KB
Binary file not shown.

‎docs/inventories/python-objects.inv

Copy file name to clipboard
3.96 KB
Binary file not shown.

‎docs/migration/replace-deprecated-functions.rst

Copy file name to clipboardExpand all lines: docs/migration/replace-deprecated-functions.rst
+39-17Lines changed: 39 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -8,17 +8,25 @@ Replacing Deprecated Functions
88
the module level. The preferred way of using semver is through the
99
:class:`~semver.version.Version` class.
1010

11-
The deprecated functions can still be used in version 2.10.0 and above. However, in
12-
future versions of semver, the deprecated functions will be removed.
11+
The deprecated functions can still be used in version 2.10.0 and above.
12+
However, in future versions of semver, the deprecated functions will be removed.
1313

14-
The following list shows the deprecated functions and how you can replace
14+
15+
Deprecated Module Level Functions
16+
---------------------------------
17+
18+
The following list shows the deprecated module level functions and how you can replace
1519
them with code which is compatible for future versions:
1620

17-
* :func:`semver.bump_major`, :func:`semver.bump_minor`, :func:`semver.bump_patch`, :func:`semver.bump_prerelease`, :func:`semver.bump_build`
21+
* :func:`semver.bump_major <semver._deprecated.bump_major>`,
22+
:func:`semver.bump_minor <semver._deprecated.bump_minor>`,
23+
:func:`semver.bump_patch <semver._deprecated.bump_patch>`,
24+
:func:`semver.bump_prerelease <semver._deprecated.bump_prerelease>`,
25+
:func:`semver.bump_build <semver._deprecated.bump_build>`
1826

1927
Replace them with the respective methods of the :class:`~semver.version.Version`
2028
class.
21-
For example, the function :func:`semver.bump_major` is replaced by
29+
For example, the function :func:`semver.bump_major <semver._deprecated.bump_major>` is replaced by
2230
:meth:`Version.bump_major <semver.version.Version.bump_major>` and calling the ``str(versionobject)``:
2331

2432
.. code-block:: python
@@ -30,12 +38,7 @@ them with code which is compatible for future versions:
3038
3139
Likewise with the other module level functions.
3240

33-
* :meth:`semver.Version.isvalid`
34-
35-
Replace it with :meth:`Version.is_valid <semver.version.Version.is_valid>`:
36-
37-
38-
* :func:`semver.finalize_version`
41+
* :func:`semver.finalize_version <semver._deprecated.finalize_version>`
3942

4043
Replace it with :meth:`Version.finalize_version <semver.version.Version.finalize_version>`:
4144

@@ -46,7 +49,7 @@ them with code which is compatible for future versions:
4649
>>> s1 == s2
4750
True
4851
49-
* :func:`semver.format_version`
52+
* :func:`semver.format_version <semver._deprecated.format_version>`
5053

5154
Replace it with ``str(versionobject)``:
5255

@@ -57,7 +60,7 @@ them with code which is compatible for future versions:
5760
>>> s1 == s2
5861
True
5962
60-
* :func:`semver.max_ver`
63+
* :func:`semver.max_ver <semver._deprecated.max_ver>`
6164

6265
Replace it with ``max(version1, version2, ...)`` or ``max([version1, version2, ...])`` and a ``key``:
6366

@@ -68,7 +71,7 @@ them with code which is compatible for future versions:
6871
>>> s1 == s2
6972
True
7073
71-
* :func:`semver.min_ver`
74+
* :func:`semver.min_ver <semver._deprecated.min_ver>`
7275

7376
Replace it with ``min(version1, version2, ...)`` or ``min([version1, version2, ...])`` and a ``key``:
7477

@@ -79,7 +82,7 @@ them with code which is compatible for future versions:
7982
>>> s1 == s2
8083
True
8184
82-
* :func:`semver.parse`
85+
* :func:`semver.parse <semver._deprecated.parse>`
8386

8487
Replace it with :meth:`Version.parse <semver.version.Version.parse>` and call
8588
:meth:`Version.to_dict <semver.version.Version.to_dict>`:
@@ -91,7 +94,7 @@ them with code which is compatible for future versions:
9194
>>> v1 == v2
9295
True
9396
94-
* :func:`semver.parse_version_info`
97+
* :func:`semver.parse_version_info <semver._deprecated.parse_version_info>`
9598

9699
Replace it with :meth:`Version.parse <semver.version.Version.parse>`:
97100

@@ -102,7 +105,7 @@ them with code which is compatible for future versions:
102105
>>> v1 == v2
103106
True
104107
105-
* :func:`semver.replace`
108+
* :func:`semver.replace <semver._deprecated.replace>`
106109

107110
Replace it with :meth:`Version.replace <semver.version.Version.replace>`:
108111

@@ -112,3 +115,22 @@ them with code which is compatible for future versions:
112115
>>> s2 = str(Version.parse('1.2.3').replace(major=2, patch=10))
113116
>>> s1 == s2
114117
True
118+
119+
120+
Deprected Version methods
121+
-------------------------
122+
123+
The following list shows the deprecated methods of the :class:`~semver.version.Version` class.
124+
125+
* :meth:`Version.isvalid <semver.version.Version.isvalid>`
126+
127+
Replace it with :meth:`Version.is_valid <semver.version.Version.is_valid>`:
128+
129+
130+
Deprecated Classes
131+
------------------
132+
133+
* :class:`VersionInfo <semver.version.VersionInfo>`
134+
135+
The class was renamed to :class:`~semver.version.Version`.
136+
Don't use the old name anymore.

‎docs/usage/access-parts-of-a-version.rst

Copy file name to clipboardExpand all lines: docs/usage/access-parts-of-a-version.rst
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ parts of a version:
2121
'build.4'
2222
2323
However, the attributes are read-only. You cannot change any of the above attributes.
24-
If you do, you get an :py:exc:`AttributeError`::
24+
If you do, you get an :py:exc:`python:AttributeError`::
2525

2626
>>> v.minor = 5
2727
Traceback (most recent call last):

‎docs/usage/access-parts-through-index.rst

Copy file name to clipboardExpand all lines: docs/usage/access-parts-through-index.rst
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ Or, as an alternative, you can pass a :func:`slice` object:
3333
>>> ver[sl]
3434
(10, 3, 2)
3535
36-
Negative numbers or undefined parts raise an :py:exc:`IndexError` exception:
36+
Negative numbers or undefined parts raise an :py:exc:`python:IndexError` exception:
3737

3838
.. code-block:: python
3939

‎docs/usage/compare-versions.rst

Copy file name to clipboardExpand all lines: docs/usage/compare-versions.rst
+2-2Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ To compare two versions depends on your type:
6262
>>> "3.5.0" > v
6363
True
6464

65-
However, if you compare incomplete strings, you get a :py:exc:`ValueError` exception::
65+
However, if you compare incomplete strings, you get a :py:exc:`python:ValueError` exception::
6666

6767
>>> v > "1.0"
6868
Traceback (most recent call last):
@@ -82,7 +82,7 @@ To compare two versions depends on your type:
8282
>>> dict(major=1) < v
8383
True
8484

85-
If the dictionary contains unknown keys, you get a :py:exc:`TypeError` exception::
85+
If the dictionary contains unknown keys, you get a :py:exc:`python:TypeError` exception::
8686

8787
>>> v > dict(major=1, unknown=42)
8888
Traceback (most recent call last):

‎docs/usage/create-a-version.rst

Copy file name to clipboardExpand all lines: docs/usage/create-a-version.rst
+4-4Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ A :class:`~semver.version.Version` instance can be created in different ways:
4141
Version(major=3, minor=4, patch=5, prerelease='pre.2', build='build.4')
4242

4343
Keep in mind, the ``major``, ``minor``, ``patch`` parts has to
44-
be positive integers or strings:
44+
be positive integers or strings, otherwise a :py:exc:`python:ValueError` is raised:
4545

4646
>>> d = {'major': -3, 'minor': 4, 'patch': 5, 'prerelease': 'pre.2', 'build': 'build.4'}
4747
>>> Version(**d)
@@ -50,7 +50,7 @@ A :class:`~semver.version.Version` instance can be created in different ways:
5050
ValueError: 'major' is negative. A version can only be positive.
5151

5252
As a minimum requirement, your dictionary needs at least the ``major``
53-
key, others can be omitted. You get a ``TypeError`` if your
53+
key, others can be omitted. You get a :py:exc:`python:TypeError` if your
5454
dictionary contains invalid keys.
5555
Only the keys ``major``, ``minor``, ``patch``, ``prerelease``, and ``build``
5656
are allowed.
@@ -87,12 +87,12 @@ Depending on your use case, the following methods are available:
8787

8888
* From a string into a dictionary
8989

90-
To access individual parts, you can use the function :func:`semver.parse`::
90+
To access individual parts, you can use the function :func:`~semver._deprecated.parse`::
9191

9292
>>> semver.parse("3.4.5-pre.2+build.4")
9393
{'major': 3, 'minor': 4, 'patch': 5, 'prerelease': 'pre.2', 'build': 'build.4'}
9494

95-
If you pass an invalid version string you will get a :py:exc:`ValueError`::
95+
If you pass an invalid version string you will get a :py:exc:`python:ValueError`::
9696

9797
>>> semver.parse("1.2")
9898
Traceback (most recent call last):

‎docs/version-policy.rst

Copy file name to clipboardExpand all lines: docs/version-policy.rst
+3-1Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,9 @@ semver Version 3
3030

3131
We will not intentionally make breaking changes in minor releases of V3.
3232

33-
Methods marked as ``deprecated`` raise a warning message when used from the :py:mod:`warnings` module.
33+
Methods marked as ``deprecated`` raise a warning message when used from the
34+
:py:mod:`python:warnings` module.
35+
Refer to section :ref:`sec_display_deprecation_warnings` to get more information about how to customize it.
3436
Check section :ref:`sec_replace_deprecated_functions` to make your code
3537
ready for future major releases.
3638

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.