Merge pull request #126 from dnvgl/fix-sphinx-build

Fix readthedocs build and poetry install with python 3.12

.readthedocs.yaml

@@ -1,6 +1,13 @@
 # .readthedocs.yaml
 # Read the Docs configuration file
+# https://docs.readthedocs.io/en/stable/config-file/v2.html
+
+# Instructions/example on how to configure for projects managed by poetry:
 # https://docs.readthedocs.io/en/stable/build-customization.html#install-dependencies-with-poetry
+# Note:   these instructions were changed in Feb 2024 to fix an issue 
+#         introduced by changes in poetry 1.8, see
+#         https://github.com/readthedocs/readthedocs.org/pull/11152
+#         https://github.com/readthedocs/readthedocs.org/issues/11150
 
 version: 2
 
@@ -13,14 +20,15 @@ build:
       # Install poetry
       # https://python-poetry.org/docs/#installing-manually
       - pip install poetry
-      # Tell poetry to not use a virtual environment
-      - poetry config virtualenvs.create false
       # Install dynamic versioning plugin
+      # https://pypi.org/project/poetry-dynamic-versioning/
       - poetry self add "poetry-dynamic-versioning[plugin]" 
     post_install:
       # Install dependencies with 'docs' dependency group
       # https://python-poetry.org/docs/managing-dependencies/#dependency-groups
-      - poetry install --with docs
+      # VIRTUAL_ENV needs to be set manually for now.
+      # See https://github.com/readthedocs/readthedocs.org/pull/11152/
+      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --with docs
 
 sphinx:
   configuration: docs/source/conf.py

docs/source/conf.py

@@ -395,13 +395,17 @@ def run(self):
 
                         if 'properties' in self.options:
                             _, props = self.get_class_members(cm, 'property')
-                            self.content += ["~%s.%s" % (fullname, prop) for prop in props if not prop.startswith('_')]
+
+                            # NOTE: `fullname` replaced by `name` due to warning in Sphinx 8.0+. Example: 
+                            #       WARNING: Summarised items should not include the current module. Replace 'qats.TimeSeries.average_frequency' with 'average_frequency'. [autosummary.import_cycle]
+                            self.content += ["~%s.%s" % (name, prop) for prop in props if not prop.startswith('_')]
 
                         if 'methods' in self.options:
                             _, methods = self.get_class_members(cm, 'method', ['__init__'])
 
-                            self.content += ["~%s.%s" % (fullname, method) for method in methods if
+                            self.content += ["~%s.%s" % (name, method) for method in methods if
                                              not method.startswith('_')]
+
                     finally:
                         return super(AutoAutoSummary, self).run()
 
@@ -416,9 +420,10 @@ def run(self):
                             typ.append('modules')
 
                         members = self.get_module_members(cm, typ=typ)
-                        self.content = ["~%s.%s" % (fullname, member) for member in members
-                                        if not member.startswith('_')]
 
+                        self.content = [member for member in members
+                                        if not member.startswith('_')]
+
                     finally:
                         return super(AutoAutoSummary, self).run()
 

pyproject.toml

@@ -24,6 +24,12 @@ Download = "https://pypi.org/project/qats/"
 Issues = "https://github.com/dnvgl/qats/issues"
 Changelog = "https://github.com/dnvgl/qats/releases"
 
+[[tool.poetry.source]]
+# fix issue that causes `poetry install` to fail for python 3.12, see:
+# https://github.com/python-poetry/poetry/issues/9293#issuecomment-2048205226
+name = "pypi-public"
+url = "https://pypi.org/simple/"
+
 [tool.poetry.dependencies]
 python = ">=3.8.1,<3.13"
 h5py = ">=3.5.0"
@@ -35,7 +41,12 @@ numpy = [
     {version = ">=1.26.0", python = ">=3.12"}
 ]
 openpyxl = ">=3.0.5"
-pandas = ">=1.1.4"
+pandas = [
+    # force pandas >=2.2.0 for python 3.12
+    # (official support for python 3.12 is introduced in pandas 2.2.0, but poetry tries to install pandas 2.0.3)
+    {version = ">=1.1.4", python = "<3.12"},
+    {version = ">=2.2.0", python = ">=3.12"}
+]
 qtpy = ">=1.9.0"
 scipy = [
     {version = ">=1.9.0", python = "<3.12"},
@@ -51,7 +62,7 @@ black = "^23.11.0"
 isort = "^5.12.0"
 
 [tool.poetry.group.docs.dependencies]
-sphinx = ">=6.1"
+sphinx = ">=7.1.2"
 furo = ">=2023.9.10"
 myst-parser = ">=2.0.0"