Skip to content

Improve documentation wording & consistency #425

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 5, 2023
Merged

Improve documentation wording & consistency #425

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ Quickstart

.. teaser-begin

A Python module for `semantic versioning`_. Simplifies comparing versions.
A Python module to simplify `semantic versioning`_.

|GHAction| |python-support| |downloads| |license| |docs| |black|
|openissues| |GHDiscussion|
Expand Down
18 changes: 12 additions & 6 deletions docs/contribute/doc-semver.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,13 +19,19 @@ used efficiently.
A new feature is *not* complete if it isn't proberly documented. A good
documentation includes:

* **Type annotations**

This library supports type annotations. Therefore, each function
or method requires types for each arguments and return objects.
Exception of this rule is ``self``.

* **A docstring**

Each docstring contains a summary line, a linebreak, an optional
directive (see next item), the description of its arguments in
`Sphinx style`_, and an optional doctest.
The docstring is extracted and reused in the :ref:`api` section.
An appropriate docstring should look like this::
An appropriate docstring looks like this::

def to_tuple(self) -> VersionTuple:
"""
Expand Down Expand Up @@ -70,11 +76,11 @@ documentation includes:

* **The documentation**

A docstring is good, but in most cases it's too dense. API documentation
cannot replace a good user documentation. Describe how
to use your new feature in our documentation. Here you can give your
readers more examples, describe it in a broader context or show
edge cases.
A docstring is good, but in most cases it is too short. API documentation
cannot replace good user documentation.
Describe *how* to use your new feature in the documentation.
Here you can give your readers more examples, describe it in a broader
context, or show edge cases.


.. _Sphinx style: https://sphinx-rtd-tutorial.rtfd.io/en/latest/docstrings.html
23 changes: 11 additions & 12 deletions docs/migration/replace-deprecated-functions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,19 +8,18 @@ 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. In version 3 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
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`

Replace them with the respective methods of the :class:`~semver.version.Version`
class.
For example, the function :func:`semver.bump_major` is replaced by
:meth:`~semver.version.Version.bump_major` and calling the ``str(versionobject)``:
:meth:`Version.bump_major <semver.version.Version.bump_major>` and calling the ``str(versionobject)``:

.. code-block:: python

Expand All @@ -31,14 +30,14 @@ them with code which is compatible for future versions:

Likewise with the other module level functions.

* :func:`semver.Version.isvalid`
* :meth:`semver.Version.isvalid`

Replace it with :meth:`semver.version.Version.is_valid`:
Replace it with :meth:`Version.is_valid <semver.version.Version.is_valid>`:


* :func:`semver.finalize_version`

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

.. code-block:: python

Expand Down Expand Up @@ -71,7 +70,7 @@ them with code which is compatible for future versions:

* :func:`semver.min_ver`

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

.. code-block:: python

Expand All @@ -82,8 +81,8 @@ them with code which is compatible for future versions:

* :func:`semver.parse`

Replace it with :meth:`semver.version.Version.parse` and call
:meth:`semver.version.Version.to_dict`:
Replace it with :meth:`Version.parse <semver.version.Version.parse>` and call
:meth:`Version.to_dict <semver.version.Version.to_dict>`:

.. code-block:: python

Expand All @@ -94,7 +93,7 @@ them with code which is compatible for future versions:

* :func:`semver.parse_version_info`

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

.. code-block:: python

Expand All @@ -105,7 +104,7 @@ them with code which is compatible for future versions:

* :func:`semver.replace`

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

.. code-block:: python

Expand Down