Fix documentation version sorting (#16)

* Update project requirement and constraint files * Update tox configuration to also use Python v3.11 for testing * Update Sphinx configuration to search for git tags of format "X.Y.Z"
iqm-finland · Oct 16, 2023 · dd4a0a4 · dd4a0a4
1 parent e606903
commit dd4a0a4
Show file tree

Hide file tree

Showing 9 changed files with 49 additions and 99 deletions.
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -2,6 +2,11 @@
 Changelog
 =========
 
+Version 0.3.2 (2023-10-16)
+--------------------------
+
+* Fix a bug in documentation version sorting.
+
 Version 0.3.1 (2023-08-11)
 --------------------------
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -143,7 +143,7 @@
 }
 
 # -- Options for sphinx_multiversion --------------------------------------------------
-smv_tag_whitelist = r'^[0-9]+\.[0-9]+$'  # Allow tags that match format "X.Y"
+smv_tag_whitelist = r'^[0-9]+\.[0-9]+\.[0-9]+$'  # Allow tags that match format "X.Y.Z"
 smv_branch_whitelist = '$-'  # Exclude all local branches in versions list by using unmatchable pattern
 smv_remote_whitelist = '$-'  # Exclude all remote branches in versions list by using unmatchable pattern
 smv_released_pattern = r'^refs/tags/.*$'  # Tags recognized as releases

diff --git a/pyproject.toml b/pyproject.toml
@@ -16,7 +16,8 @@ classifiers = [
 ]
 requires-python = ">=3.9, <3.12"
 dependencies = [
-    "sphinx >= 4.5.0"
+    "sphinx >= 4.5.0",
+    "packaging >= 23.0"
 ]
 
 [project.urls]

diff --git a/requirements/base.txt b/requirements/base.txt
@@ -1,5 +1,5 @@
 #
-# This file is autogenerated by pip-compile with Python 3.9
+# This file is autogenerated by pip-compile with Python 3.11
 # by the following command:
 #
 #    pip-compile --no-emit-index-url --output-file=requirements/base.txt pyproject.toml requirements/constraints.txt
@@ -34,6 +34,13 @@ click==8.1.3
     # via
     #   -r requirements/constraints.txt
     #   black
+colorama==0.4.6
+    # via
+    #   -r requirements/constraints.txt
+    #   click
+    #   pylint
+    #   pytest
+    #   sphinx
 coverage[toml]==7.2.1
     # via
     #   -r requirements/constraints.txt
@@ -47,10 +54,6 @@ docutils==0.17.1
     #   -r requirements/constraints.txt
     #   pydata-sphinx-theme
     #   sphinx
-exceptiongroup==1.1.2
-    # via
-    #   -r requirements/constraints.txt
-    #   pytest
 idna==3.4
     # via
     #   -r requirements/constraints.txt
@@ -59,10 +62,6 @@ imagesize==1.4.1
     # via
     #   -r requirements/constraints.txt
     #   sphinx
-importlib-metadata==6.8.0
-    # via
-    #   -r requirements/constraints.txt
-    #   sphinx
 iniconfig==2.0.0
     # via
     #   -r requirements/constraints.txt
@@ -101,6 +100,7 @@ packaging==23.0
     #   pydata-sphinx-theme
     #   pytest
     #   sphinx
+    #   sphinx-multiversion-contrib (pyproject.toml)
 pathspec==0.11.0
     # via
     #   -r requirements/constraints.txt
@@ -178,25 +178,14 @@ sphinxcontrib-serializinghtml==1.1.5
     # via
     #   -r requirements/constraints.txt
     #   sphinx
-tomli==2.0.1
-    # via
-    #   -r requirements/constraints.txt
-    #   black
-    #   coverage
-    #   mypy
-    #   pylint
-    #   pytest
 tomlkit==0.11.6
     # via
     #   -r requirements/constraints.txt
     #   pylint
 typing-extensions==4.5.0
     # via
     #   -r requirements/constraints.txt
-    #   astroid
-    #   black
     #   mypy
-    #   pylint
 urllib3==1.26.14
     # via
     #   -r requirements/constraints.txt
@@ -205,7 +194,3 @@ wrapt==1.15.0
     # via
     #   -r requirements/constraints.txt
     #   astroid
-zipp==3.16.2
-    # via
-    #   -r requirements/constraints.txt
-    #   importlib-metadata
diff --git a/requirements/constraints.txt b/requirements/constraints.txt
@@ -1,5 +1,5 @@
 #
-# This file is autogenerated by pip-compile with Python 3.9
+# This file is autogenerated by pip-compile with Python 3.11
 # by the following command:
 #
 #    pip-compile --extra=test,docs --no-emit-index-url --output-file=requirements/constraints.txt pyproject.toml
@@ -20,6 +20,12 @@ charset-normalizer==3.1.0
     # via requests
 click==8.1.3
     # via black
+colorama==0.4.6
+    # via
+    #   click
+    #   pylint
+    #   pytest
+    #   sphinx
 coverage[toml]==7.2.1
     # via pytest-cov
 dill==0.3.6
@@ -28,14 +34,10 @@ docutils==0.17.1
     # via
     #   pydata-sphinx-theme
     #   sphinx
-exceptiongroup==1.1.2
-    # via pytest
 idna==3.4
     # via requests
 imagesize==1.4.1
     # via sphinx
-importlib-metadata==6.8.0
-    # via sphinx
 iniconfig==2.0.0
     # via pytest
 isort==5.12.0
@@ -62,6 +64,7 @@ packaging==23.0
     #   pydata-sphinx-theme
     #   pytest
     #   sphinx
+    #   sphinx-multiversion-contrib (pyproject.toml)
 pathspec==0.11.0
     # via black
 platformdirs==3.1.0
@@ -109,24 +112,11 @@ sphinxcontrib-qthelp==1.0.3
     # via sphinx
 sphinxcontrib-serializinghtml==1.1.5
     # via sphinx
-tomli==2.0.1
-    # via
-    #   black
-    #   coverage
-    #   mypy
-    #   pylint
-    #   pytest
 tomlkit==0.11.6
     # via pylint
 typing-extensions==4.5.0
-    # via
-    #   astroid
-    #   black
-    #   mypy
-    #   pylint
+    # via mypy
 urllib3==1.26.14
     # via requests
 wrapt==1.15.0
     # via astroid
-zipp==3.16.2
-    # via importlib-metadata
diff --git a/requirements/docs.txt b/requirements/docs.txt
@@ -1,5 +1,5 @@
 #
-# This file is autogenerated by pip-compile with Python 3.9
+# This file is autogenerated by pip-compile with Python 3.11
 # by the following command:
 #
 #    pip-compile --extra=docs --no-emit-index-url --output-file=requirements/docs.txt pyproject.toml requirements/constraints.txt
@@ -34,6 +34,13 @@ click==8.1.3
     # via
     #   -r requirements/constraints.txt
     #   black
+colorama==0.4.6
+    # via
+    #   -r requirements/constraints.txt
+    #   click
+    #   pylint
+    #   pytest
+    #   sphinx
 coverage[toml]==7.2.1
     # via
     #   -r requirements/constraints.txt
@@ -47,10 +54,6 @@ docutils==0.17.1
     #   -r requirements/constraints.txt
     #   pydata-sphinx-theme
     #   sphinx
-exceptiongroup==1.1.2
-    # via
-    #   -r requirements/constraints.txt
-    #   pytest
 idna==3.4
     # via
     #   -r requirements/constraints.txt
@@ -59,10 +62,6 @@ imagesize==1.4.1
     # via
     #   -r requirements/constraints.txt
     #   sphinx
-importlib-metadata==6.8.0
-    # via
-    #   -r requirements/constraints.txt
-    #   sphinx
 iniconfig==2.0.0
     # via
     #   -r requirements/constraints.txt
@@ -101,6 +100,7 @@ packaging==23.0
     #   pydata-sphinx-theme
     #   pytest
     #   sphinx
+    #   sphinx-multiversion-contrib (pyproject.toml)
 pathspec==0.11.0
     # via
     #   -r requirements/constraints.txt
@@ -180,25 +180,14 @@ sphinxcontrib-serializinghtml==1.1.5
     # via
     #   -r requirements/constraints.txt
     #   sphinx
-tomli==2.0.1
-    # via
-    #   -r requirements/constraints.txt
-    #   black
-    #   coverage
-    #   mypy
-    #   pylint
-    #   pytest
 tomlkit==0.11.6
     # via
     #   -r requirements/constraints.txt
     #   pylint
 typing-extensions==4.5.0
     # via
     #   -r requirements/constraints.txt
-    #   astroid
-    #   black
     #   mypy
-    #   pylint
 urllib3==1.26.14
     # via
     #   -r requirements/constraints.txt
@@ -207,7 +196,3 @@ wrapt==1.15.0
     # via
     #   -r requirements/constraints.txt
     #   astroid
-zipp==3.16.2
-    # via
-    #   -r requirements/constraints.txt
-    #   importlib-metadata
diff --git a/requirements/test.txt b/requirements/test.txt
@@ -1,5 +1,5 @@
 #
-# This file is autogenerated by pip-compile with Python 3.9
+# This file is autogenerated by pip-compile with Python 3.11
 # by the following command:
 #
 #    pip-compile --extra=test --no-emit-index-url --output-file=requirements/test.txt pyproject.toml requirements/constraints.txt
@@ -36,6 +36,13 @@ click==8.1.3
     # via
     #   -r requirements/constraints.txt
     #   black
+colorama==0.4.6
+    # via
+    #   -r requirements/constraints.txt
+    #   click
+    #   pylint
+    #   pytest
+    #   sphinx
 coverage[toml]==7.2.1
     # via
     #   -r requirements/constraints.txt
@@ -49,10 +56,6 @@ docutils==0.17.1
     #   -r requirements/constraints.txt
     #   pydata-sphinx-theme
     #   sphinx
-exceptiongroup==1.1.2
-    # via
-    #   -r requirements/constraints.txt
-    #   pytest
 idna==3.4
     # via
     #   -r requirements/constraints.txt
@@ -61,10 +64,6 @@ imagesize==1.4.1
     # via
     #   -r requirements/constraints.txt
     #   sphinx
-importlib-metadata==6.8.0
-    # via
-    #   -r requirements/constraints.txt
-    #   sphinx
 iniconfig==2.0.0
     # via
     #   -r requirements/constraints.txt
@@ -106,6 +105,7 @@ packaging==23.0
     #   pydata-sphinx-theme
     #   pytest
     #   sphinx
+    #   sphinx-multiversion-contrib (pyproject.toml)
 pathspec==0.11.0
     # via
     #   -r requirements/constraints.txt
@@ -188,25 +188,14 @@ sphinxcontrib-serializinghtml==1.1.5
     # via
     #   -r requirements/constraints.txt
     #   sphinx
-tomli==2.0.1
-    # via
-    #   -r requirements/constraints.txt
-    #   black
-    #   coverage
-    #   mypy
-    #   pylint
-    #   pytest
 tomlkit==0.11.6
     # via
     #   -r requirements/constraints.txt
     #   pylint
 typing-extensions==4.5.0
     # via
     #   -r requirements/constraints.txt
-    #   astroid
-    #   black
     #   mypy
-    #   pylint
 urllib3==1.26.14
     # via
     #   -r requirements/constraints.txt
@@ -215,7 +204,3 @@ wrapt==1.15.0
     # via
     #   -r requirements/constraints.txt
     #   astroid
-zipp==3.16.2
-    # via
-    #   -r requirements/constraints.txt
-    #   importlib-metadata
diff --git a/src/sphinx_multiversion/main.py b/src/sphinx_multiversion/main.py
@@ -19,6 +19,7 @@
 import tempfile
 from typing import Any, Union
 
+from packaging.version import parse
 from sphinx.config import Config as sphinx_config
 from sphinx.errors import ConfigError as sphinx_config_error
 from sphinx.project import Project as sphinx_project
@@ -284,11 +285,9 @@ def main(  # pylint: disable=too-many-branches,too-many-locals,too-many-statemen
     else:
         gitrefs = sorted(gitrefs, key=lambda x: (x.is_remote, *x))
 
-    # TODO: Refactor the line to enable type checking with mypy
-    # git refs by default are just strings, and we need to extract symver to be able to reasonably sort versions
-    # fmt: off
-    gitrefs = sorted(gitrefs, key=lambda x: float(re.match(config.smv_symver_pattern, x.refname).group(1)))  # type: ignore  # pylint: disable=line-too-long
-    # fmt: on
+    # git refs by default are just strings (e.g. "refs/tags/10.11"), and we need
+    # to extract semver to be able to sort versions
+    gitrefs.sort(key=lambda gitref: parse(gitref.refname.split("/")[-1]))
 
     logger = logging.getLogger(__name__)
     released_versions = []

diff --git a/tox.ini b/tox.ini
@@ -29,7 +29,7 @@ commands =
     python -m piptools compile -q --no-emit-index-url --extra=test      --output-file=requirements/test.txt requirements/constraints.txt pyproject.toml {posargs}
     python -m piptools compile -q --no-emit-index-url --extra=docs      --output-file=requirements/docs.txt requirements/constraints.txt pyproject.toml {posargs}
 
-[testenv:py{39,310}]
+[testenv:py{39,310,311}]
 description =
     Run automated tests.
 deps =