From ca415339bd28c51931fa65d81a5f42f93fb314ef Mon Sep 17 00:00:00 2001 From: Tom Schraitle Date: Mon, 9 Oct 2023 18:00:14 +0200 Subject: [PATCH] Use meta directive for SEO --- changelog.d/pr435.doc.rst | 7 +++++++ docs/advanced/combine-pydantic-and-semver.rst | 4 ++++ docs/advanced/convert-pypi-to-semver.rst | 6 +++++- docs/advanced/create-subclasses-from-version.rst | 4 ++++ docs/advanced/deal-with-invalid-versions.rst | 4 ++++ docs/advanced/display-deprecation-warnings.rst | 4 ++++ docs/advanced/index.rst | 3 +++ docs/advanced/version-from-file.rst | 6 +++++- docs/api.rst | 4 ++++ docs/build-semver.rst | 3 +++ docs/contribute/add-changelog-entry.rst | 4 ++++ docs/contribute/doc-semver.rst | 4 ++++ docs/contribute/finish-release.rst | 4 ++++ docs/contribute/index.rst | 4 ++++ docs/contribute/prerequisites.rst | 4 ++++ docs/contribute/release-procedure.rst | 4 ++++ docs/contribute/report-bugs.rst | 4 ++++ docs/contribute/run-test-suite.rst | 4 ++++ docs/index.rst | 4 ++++ docs/install.rst | 4 ++++ docs/migration/index.rst | 3 +++ docs/migration/migratetosemver3.rst | 4 ++++ docs/migration/replace-deprecated-functions.rst | 4 ++++ docs/pysemver.rst | 4 ++++ docs/usage/access-parts-of-a-version.rst | 4 ++++ docs/usage/access-parts-through-index.rst | 4 ++++ docs/usage/check-compatible-semver-version.rst | 4 ++++ docs/usage/check-valid-semver-version.rst | 4 ++++ docs/usage/compare-versions-through-expression.rst | 4 ++++ docs/usage/compare-versions.rst | 4 ++++ docs/usage/convert-version-into-different-types.rst | 5 +++++ docs/usage/create-a-version.rst | 4 ++++ docs/usage/determine-version-equality.rst | 4 ++++ docs/usage/get-min-and-max-of-multiple-versions.rst | 4 ++++ 34 files changed, 139 insertions(+), 2 deletions(-) create mode 100644 changelog.d/pr435.doc.rst diff --git a/changelog.d/pr435.doc.rst b/changelog.d/pr435.doc.rst new file mode 100644 index 00000000..87925c3d --- /dev/null +++ b/changelog.d/pr435.doc.rst @@ -0,0 +1,7 @@ +Several small improvements for documentation: + +* Add meta description to improve SEO +* Use canonicals on ReadTheDocs (commit 87f639f) +* Pin versions for reproducable doc builds (commit 03fb990) +* Add missing :file:`.readthedocs.yaml` file (commit ec9348a) +* Correct some smaller issues when building (commit f65feab) diff --git a/docs/advanced/combine-pydantic-and-semver.rst b/docs/advanced/combine-pydantic-and-semver.rst index 3236c2a2..c7566e12 100644 --- a/docs/advanced/combine-pydantic-and-semver.rst +++ b/docs/advanced/combine-pydantic-and-semver.rst @@ -1,6 +1,10 @@ Combining Pydantic and semver ============================= +.. meta:: + :description lang=en: + Combining Pydantic and semver + According to its homepage, `Pydantic `_ "enforces type hints at runtime, and provides user friendly errors when data is invalid." diff --git a/docs/advanced/convert-pypi-to-semver.rst b/docs/advanced/convert-pypi-to-semver.rst index 04737d29..82b4f5a3 100644 --- a/docs/advanced/convert-pypi-to-semver.rst +++ b/docs/advanced/convert-pypi-to-semver.rst @@ -1,6 +1,10 @@ -Converting versions between PyPI and semver +Converting Versions between PyPI and semver =========================================== +.. meta:: + :description lang=en: + Converting versions between PyPI and semver + .. Link https://packaging.pypa.io/en/latest/_modules/packaging/version.html#InvalidVersion diff --git a/docs/advanced/create-subclasses-from-version.rst b/docs/advanced/create-subclasses-from-version.rst index 7e99e217..3a5194f4 100644 --- a/docs/advanced/create-subclasses-from-version.rst +++ b/docs/advanced/create-subclasses-from-version.rst @@ -3,6 +3,10 @@ Creating Subclasses from Version ================================ +.. meta:: + :description lang=en: + Creating subclasses from Version class + If you do not like creating functions to modify the behavior of semver (as shown in section :ref:`sec_dealing_with_invalid_versions`), you can also create a subclass of the :class:`Version ` class. diff --git a/docs/advanced/deal-with-invalid-versions.rst b/docs/advanced/deal-with-invalid-versions.rst index ee5e5704..120d82a0 100644 --- a/docs/advanced/deal-with-invalid-versions.rst +++ b/docs/advanced/deal-with-invalid-versions.rst @@ -3,6 +3,10 @@ Dealing with Invalid Versions ============================= +.. meta:: + :description lang=en: + Dealing with invalid versions + As semver follows the semver specification, it cannot parse version strings which are considered "invalid" by that specification. The semver library cannot know all the possible variations so you need to help the diff --git a/docs/advanced/display-deprecation-warnings.rst b/docs/advanced/display-deprecation-warnings.rst index 825bbe76..a2fb8342 100644 --- a/docs/advanced/display-deprecation-warnings.rst +++ b/docs/advanced/display-deprecation-warnings.rst @@ -3,6 +3,10 @@ Displaying Deprecation Warnings =============================== +.. meta:: + :description lang=en: + Displaying and filtering deprecation warnings + By default, deprecation warnings are `ignored in Python `_. This also affects semver's own warnings. diff --git a/docs/advanced/index.rst b/docs/advanced/index.rst index 47c23b9d..26cd5729 100644 --- a/docs/advanced/index.rst +++ b/docs/advanced/index.rst @@ -1,6 +1,9 @@ Advanced topics =============== +.. meta:: + :description lang=en: + Advanced topics for Python semver .. toctree:: :maxdepth: 1 diff --git a/docs/advanced/version-from-file.rst b/docs/advanced/version-from-file.rst index b49ff36b..5d484438 100644 --- a/docs/advanced/version-from-file.rst +++ b/docs/advanced/version-from-file.rst @@ -1,8 +1,12 @@ .. _sec_reading_versions_from_file: -Reading versions from file +Reading Versions from File ========================== +.. meta:: + :description lang=en: + Reading versions from file + In cases where a version is stored inside a file, one possible solution is to use the following function: diff --git a/docs/api.rst b/docs/api.rst index f545ebc5..0ce4012c 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -3,6 +3,10 @@ API Reference ============= +.. meta:: + :description lang=en: + API reference about Python semver + .. currentmodule:: semver diff --git a/docs/build-semver.rst b/docs/build-semver.rst index c938a1ee..b5626d22 100644 --- a/docs/build-semver.rst +++ b/docs/build-semver.rst @@ -3,6 +3,9 @@ Building semver =============== +.. meta:: + :description lang=en: + Building semver .. _PEP 517: https://www.python.org/dev/peps/pep-0517/ .. _PEP 621: https://www.python.org/dev/peps/pep-0621/ diff --git a/docs/contribute/add-changelog-entry.rst b/docs/contribute/add-changelog-entry.rst index c0d426a8..30215c76 100644 --- a/docs/contribute/add-changelog-entry.rst +++ b/docs/contribute/add-changelog-entry.rst @@ -3,5 +3,9 @@ Adding a Changelog Entry ======================== +.. meta:: + :description lang=en: + Adding a changelog entry with Towncrier + .. include:: ../../changelog.d/README.rst :start-after: -text-begin- \ No newline at end of file diff --git a/docs/contribute/doc-semver.rst b/docs/contribute/doc-semver.rst index e5237eaf..217b1d21 100644 --- a/docs/contribute/doc-semver.rst +++ b/docs/contribute/doc-semver.rst @@ -3,6 +3,10 @@ Documenting semver ================== +.. meta:: + :description lang=en: + Documenting semver with type annotations, docstrings, Sphinx directives + Documenting the features of semver is very important. It gives our developers an overview what is possible with semver, how it "feels", and how it is used efficiently. diff --git a/docs/contribute/finish-release.rst b/docs/contribute/finish-release.rst index 947fcf96..d1fcce2c 100644 --- a/docs/contribute/finish-release.rst +++ b/docs/contribute/finish-release.rst @@ -3,6 +3,10 @@ Finish the Release ================== +.. meta:: + :description lang=en: + Finish the semver release by creating tags + 1. Create a tag: $ git tag -a x.x.x diff --git a/docs/contribute/index.rst b/docs/contribute/index.rst index f09e6418..30960ace 100644 --- a/docs/contribute/index.rst +++ b/docs/contribute/index.rst @@ -3,6 +3,10 @@ Contributing to semver ====================== +.. meta:: + :description lang=en: + Contributing to Python semver + The semver source code is managed using Git and is hosted on GitHub:: git clone git://github.com/python-semver/python-semver diff --git a/docs/contribute/prerequisites.rst b/docs/contribute/prerequisites.rst index 79bbb571..1084d247 100644 --- a/docs/contribute/prerequisites.rst +++ b/docs/contribute/prerequisites.rst @@ -1,6 +1,10 @@ Prerequisites ------------- +.. meta:: + :description lang=en: + Overview of prerequisites for contributing + .. -text-begin- Before you make changes to the code, we would highly appreciate if you diff --git a/docs/contribute/release-procedure.rst b/docs/contribute/release-procedure.rst index c02148fe..b18672fb 100644 --- a/docs/contribute/release-procedure.rst +++ b/docs/contribute/release-procedure.rst @@ -1,6 +1,10 @@ Release Procedure ================= +.. meta:: + :description lang=en: + Release procedure: prepare and create the release + The following procedures gives a short overview of what steps are needed to create a new release. diff --git a/docs/contribute/report-bugs.rst b/docs/contribute/report-bugs.rst index fa14eb18..614098b9 100644 --- a/docs/contribute/report-bugs.rst +++ b/docs/contribute/report-bugs.rst @@ -3,6 +3,10 @@ Reporting Bugs and Asking Questions ----------------------------------- +.. meta:: + :description lang=en: + Reporting bugs and asking questions about semver + If you think you have encountered a bug in semver or have an idea for a new feature? Great! We like to hear from you! diff --git a/docs/contribute/run-test-suite.rst b/docs/contribute/run-test-suite.rst index 07c49fff..22f4ebc0 100644 --- a/docs/contribute/run-test-suite.rst +++ b/docs/contribute/run-test-suite.rst @@ -3,6 +3,10 @@ Running the Test Suite ====================== +.. meta:: + :description lang=en: + Running the test suite through tox + We use `pytest`_ and `tox`_ to run tests against all supported Python versions. All test dependencies are resolved automatically. diff --git a/docs/index.rst b/docs/index.rst index 0f1f32d6..d0b15882 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,6 +1,10 @@ Semver |version| -- Semantic Versioning ======================================= +.. meta:: + :description lang=en: + Semantic versioning for Python + .. include:: readme.rst diff --git a/docs/install.rst b/docs/install.rst index dee441de..380a4bb5 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -1,6 +1,10 @@ Installing semver ================= +.. meta:: + :description lang=en: + Installing semver on the system + Release Policy -------------- diff --git a/docs/migration/index.rst b/docs/migration/index.rst index c6af7c05..74c3d866 100644 --- a/docs/migration/index.rst +++ b/docs/migration/index.rst @@ -1,6 +1,9 @@ Migrating to semver3 ==================== +.. meta:: + :description lang=en: + Migrating from semver version 2 to version 3 .. toctree:: :maxdepth: 1 diff --git a/docs/migration/migratetosemver3.rst b/docs/migration/migratetosemver3.rst index e8b5c9ab..2c09fb41 100644 --- a/docs/migration/migratetosemver3.rst +++ b/docs/migration/migratetosemver3.rst @@ -3,6 +3,10 @@ Migrating from semver2 to semver3 ================================= +.. meta:: + :description lang=en: + Migrating from semver2 to semver3 + This section describes the visible differences for users and how your code stays compatible for semver3. Some changes are backward incompatible. diff --git a/docs/migration/replace-deprecated-functions.rst b/docs/migration/replace-deprecated-functions.rst index c0091b73..df0d799a 100644 --- a/docs/migration/replace-deprecated-functions.rst +++ b/docs/migration/replace-deprecated-functions.rst @@ -3,6 +3,10 @@ Replacing Deprecated Functions ============================== +.. meta:: + :description lang=en: + Replacing deprecated functions + .. versionchanged:: 2.10.0 The development team of semver has decided to deprecate certain functions on the module level. The preferred way of using semver is through the diff --git a/docs/pysemver.rst b/docs/pysemver.rst index b0896eea..cea32e6c 100644 --- a/docs/pysemver.rst +++ b/docs/pysemver.rst @@ -3,6 +3,10 @@ pysemver |version| ================== +.. meta:: + :description lang=en: + Commandline tool pysemver describing all commands and options + Synopsis -------- diff --git a/docs/usage/access-parts-of-a-version.rst b/docs/usage/access-parts-of-a-version.rst index b1ce3a14..d8a15cb4 100644 --- a/docs/usage/access-parts-of-a-version.rst +++ b/docs/usage/access-parts-of-a-version.rst @@ -3,6 +3,10 @@ Accessing Parts of a Version Through Names ========================================== +.. meta:: + :description lang=en: + Accessing parts of a version through names + The :class:`~semver.version.Version` class contains attributes to access the different parts of a version: diff --git a/docs/usage/access-parts-through-index.rst b/docs/usage/access-parts-through-index.rst index 4553056a..cc6b0c2b 100644 --- a/docs/usage/access-parts-through-index.rst +++ b/docs/usage/access-parts-through-index.rst @@ -3,6 +3,10 @@ Accessing Parts Through Index Numbers ===================================== +.. meta:: + :description lang=en: + Accessing parts through index numbers + .. versionadded:: 2.10.0 Another way to access parts of a version is to use an index notation. The underlying diff --git a/docs/usage/check-compatible-semver-version.rst b/docs/usage/check-compatible-semver-version.rst index 20330456..4cf47908 100644 --- a/docs/usage/check-compatible-semver-version.rst +++ b/docs/usage/check-compatible-semver-version.rst @@ -1,6 +1,10 @@ Checking for a Compatible Semver Version ======================================== +.. meta:: + :description lang=en: + Check for a compatible semver version + To check if a *change* from a semver version ``a`` to a semver version ``b`` is *compatible* according to semver rule, use the method :meth:`~semver.version.Version.is_compatible`. diff --git a/docs/usage/check-valid-semver-version.rst b/docs/usage/check-valid-semver-version.rst index bdd57e7a..2e016c6d 100644 --- a/docs/usage/check-valid-semver-version.rst +++ b/docs/usage/check-valid-semver-version.rst @@ -1,6 +1,10 @@ Checking for a Valid Semver Version =================================== +.. meta:: + :description lang=en: + Checking for a valid semver version + If you need to check a string if it is a valid semver version, use the classmethod :meth:`~semver.version.Version.is_valid`: diff --git a/docs/usage/compare-versions-through-expression.rst b/docs/usage/compare-versions-through-expression.rst index e2dee4d6..5b05a123 100644 --- a/docs/usage/compare-versions-through-expression.rst +++ b/docs/usage/compare-versions-through-expression.rst @@ -1,6 +1,10 @@ Comparing Versions through an Expression ======================================== +.. meta:: + :description lang=en: + Comparing versions through an expression + If you need a more fine-grained approach of comparing two versions, use the :meth:`~semver.version.Version.match` function. It expects two arguments: diff --git a/docs/usage/compare-versions.rst b/docs/usage/compare-versions.rst index 839ad68b..714cf8ba 100644 --- a/docs/usage/compare-versions.rst +++ b/docs/usage/compare-versions.rst @@ -1,6 +1,10 @@ Comparing Versions ================== +.. meta:: + :description lang=en: + Comparing versions with semver.compare and the Version class + To compare two versions depends on your type: * **Two strings** diff --git a/docs/usage/convert-version-into-different-types.rst b/docs/usage/convert-version-into-different-types.rst index 6a447d0d..c75992f1 100644 --- a/docs/usage/convert-version-into-different-types.rst +++ b/docs/usage/convert-version-into-different-types.rst @@ -3,6 +3,11 @@ Converting a Version instance into Different Types ================================================== +.. meta:: + :description lang=en: + Converting a version instance into different types + + Sometimes it is needed to convert a :class:`~semver.version.Version` instance into a different type. For example, for displaying or to access all parts. diff --git a/docs/usage/create-a-version.rst b/docs/usage/create-a-version.rst index 9404ae4b..06165235 100644 --- a/docs/usage/create-a-version.rst +++ b/docs/usage/create-a-version.rst @@ -1,6 +1,10 @@ Creating a Version ================== +.. meta:: + :description lang=en: + Creating a version using different methods + .. versionchanged:: 3.0.0 The former :class:`~semver.version.VersionInfo` class diff --git a/docs/usage/determine-version-equality.rst b/docs/usage/determine-version-equality.rst index 211743c9..ba4125ed 100644 --- a/docs/usage/determine-version-equality.rst +++ b/docs/usage/determine-version-equality.rst @@ -1,6 +1,10 @@ Determining Version Equality ============================ +.. meta:: + :description lang=en: + Determining verison equality + Version equality means for semver, that major, minor, patch, and prerelease parts are equal in both versions you compare. The build part is ignored. For example:: diff --git a/docs/usage/get-min-and-max-of-multiple-versions.rst b/docs/usage/get-min-and-max-of-multiple-versions.rst index e143162a..35ba77b4 100644 --- a/docs/usage/get-min-and-max-of-multiple-versions.rst +++ b/docs/usage/get-min-and-max-of-multiple-versions.rst @@ -3,6 +3,10 @@ Getting Minimum and Maximum of Multiple Versions ================================================ +.. meta:: + :description lang=en: + Getting minimum and maximum of multiple versions + .. versionchanged:: 2.10.2 The functions :func:`semver.max_ver` and :func:`semver.min_ver` are deprecated in favor of their builtin counterparts :func:`max` and :func:`min`.