tweak documentation a little + change how cms version is defined (#1671)

* make the docs' version automatically match the cms version
* define the version in pyproject.toml instead of __init__.py
* show version in sidebar, make sidebar scroll with the page

Author: prandla

cms/__init__.py

@@ -46,9 +46,6 @@
 ]
 
 
-__version__ = "1.6.dev0"
-
-
 # Instantiate or import these objects.
 
 
@@ -79,3 +76,7 @@
     get_service_address, get_service_shards, contest_id_from_args, \
     default_argument_parser
 from .plugin import plugin_list
+
+# Define version here for backwards compatibility, just in case anything reads it.
+import importlib.metadata
+__version__ = importlib.metadata.version("cms")

docs/conf.py

@@ -13,6 +13,7 @@
 
 import sys
 import os
+import tomllib
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -54,8 +55,9 @@
 #
 # See: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-version
 #
-version = "1.5"
-release = "1.5.1"
+with open("../pyproject.toml", 'rb') as f:
+    version = tomllib.load(f)['project']['version']
+    release = version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -101,7 +103,10 @@
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#html_theme_options = {}
+html_theme_options = {
+    'fixed_sidebar': True,
+    'description': "Version " + version,
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []

pyproject.toml

@@ -1,6 +1,7 @@
 [project]
-dynamic = ["version", "entry-points", "scripts"]
+dynamic = ["entry-points", "scripts"]
 name = "cms"
+version = "1.6.dev0"
 license = "AGPL-3.0-or-later"
 maintainers = [ { name = "The CMS development team", email = "contestms@googlegroups.com" } ]
 readme = "README.md"

setup.py

@@ -28,9 +28,6 @@
 
 """
 
-import os
-import re
-
 from setuptools import setup, find_packages
 from setuptools.command.build import build
 
@@ -92,18 +89,6 @@
     ],
 }
 
-
-def find_version():
-    """Return the version string obtained from cms/__init__.py"""
-    path = os.path.join("cms", "__init__.py")
-    with open(path, "rt", encoding="utf-8") as f:
-        version_match = re.search(r"^__version__ = ['\"]([^'\"]*)['\"]",
-                                  f.read(), re.M)
-    if version_match is not None:
-        return version_match.group(1)
-    raise RuntimeError("Unable to find version string.")
-
-
 # We piggyback the translation catalogs compilation onto build since
 # the po and mofiles will be part of the package data for cms.locale,
 # which is collected at this stage.
@@ -113,7 +98,6 @@ class build_with_l10n(build):
 
 setup(
     name="cms",
-    version=find_version(),
     packages=find_packages(),
     package_data=PACKAGE_DATA,
     cmdclass={"build": build_with_l10n},