Use meta directive for SEO

tomschr · tomschr · commit ca415339bd28 · 2023-10-09T18:31:55.000+02:00
diff --git a/changelog.d/pr435.doc.rst 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
@@ -1,6 +1,10 @@
 Combining Pydantic and semver
 =============================
 
+.. meta::
+   :description lang=en:
+      Combining Pydantic and semver
+
 According to its homepage, `Pydantic <https://pydantic-docs.helpmanual.io>`_
 "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
@@ -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
@@ -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 <semver.version.Version>` class.
diff --git 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
@@ -3,6 +3,10 @@
 Displaying Deprecation Warnings
 ===============================
 
+.. meta::
+   :description lang=en:
+      Displaying and filtering deprecation warnings
+
 By default,  deprecation warnings are `ignored in Python <https://docs.python.org/3/library/warnings.html#warning-categories>`_.
 This also affects semver's own warnings.
 
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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-
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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`.
