resolve the import_cycle warning (#143)

* remove obsolete check

* install other deps before `sphinx`

* pin `sphinx_rtd_theme` to <3 if we're testing `sphinx=5`

* install `imghdr` for python 3.13

* skip `sphinx=5.3` on `python=3.13`

* change the simple example module to a package

* adapt the example docs

* suppress the import cycle warning

* add the forgotten `__init__.py`

* don't use `sphinx>=8.2` for now

(that appears to break backwards compatibility with other extensions)

Author: keewis

.github/workflows/ci.yaml

@@ -17,10 +17,14 @@ jobs:
         python-version: ["3.9", "3.12", "3.13"]
         sphinx-version: ["5.3", "6.2", "7.3", "7.4", "8.0", "8.1"]
         exclude:
+          # sphinx>=8 requires at least python 3.10
           - python-version: "3.9"
             sphinx-version: "8.0"
           - python-version: "3.9"
             sphinx-version: "8.1"
+          # sphinx<6.2 uses imghdr, which was removed in python 3.13
+          - python-version: "3.13"
+            sphinx-version: "5.3"
 
     steps:
       - name: checkout the repository
@@ -44,15 +48,15 @@ jobs:
       - name: upgrade pip
         run: python -m pip install --upgrade pip
 
+      - name: install other dependencies
+        run: python -m pip install -r ci/requirements.txt
+
       - name: install sphinx
         run: |
-          python -m pip install "sphinx==${{matrix.sphinx-version}}"
-          if [[ "${{matrix.sphinx-version}}" < "4.0" ]]; then
-              python -m pip install "jinja2<3.1" "docutils<0.18"
+          if [[ "${{matrix.sphinx-version}}" < "6.0" ]]; then
+            python -m pip install "sphinx_rtd_theme<3.0"
           fi
-
-      - name: install other dependencies
-        run: python -m pip install -r ci/requirements.txt
+          python -m pip install "sphinx==${{matrix.sphinx-version}}"
 
       - name: install the extension
         run: python -m pip install .

docs/conf.py

@@ -68,6 +68,11 @@
 master_doc = "index"
 suffix = ".rst"
 
+# temporarily supress warnings
+suppress_warnings = [
+    # emitted because we're trying to redirect to a absolute import path
+    "autosummary.import_cycle",
+]
 
 # -- Options for HTML output -------------------------------------------------
 

docs/example/__init__.py

@@ -0,0 +1,2 @@
+from example.accessors import Test2Accessor, TestAccessor  # noqa: F401
+from example.object import Example  # noqa: F401

docs/example.py renamed to docs/example/accessors.py

@@ -1,32 +1,4 @@
-class CachedAccessor:
-    def __init__(self, name, accessor):
-        self._name = name
-        self._accessor = accessor
-
-    def __get__(self, obj, cls):
-        if obj is None:
-            return self._accessor
-
-        accessor_obj = self._accessor(obj)
-        setattr(obj, self._name, accessor_obj)
-
-        return accessor_obj
-
-
-class Example:
-    """test class"""
-
-    def __init__(self, data):
-        self._data = data
-
-
-def register_accessor(name):
-    def func(accessor):
-        setattr(Example, name, CachedAccessor(name, accessor))
-
-        return accessor
-
-    return func
+from example.extensions import CachedAccessor, register_accessor
 
 
 @register_accessor("test")

docs/example/extensions.py

@@ -0,0 +1,25 @@
+from example.object import Example
+
+
+class CachedAccessor:
+    def __init__(self, name, accessor):
+        self._name = name
+        self._accessor = accessor
+
+    def __get__(self, obj, cls):
+        if obj is None:
+            return self._accessor
+
+        accessor_obj = self._accessor(obj)
+        setattr(obj, self._name, accessor_obj)
+
+        return accessor_obj
+
+
+def register_accessor(name):
+    def func(accessor):
+        setattr(Example, name, CachedAccessor(name, accessor))
+
+        return accessor
+
+    return func

docs/example/object.py

@@ -0,0 +1,5 @@
+class Example:
+    """test class"""
+
+    def __init__(self, data):
+        self._data = data

docs/examples.rst

@@ -10,9 +10,9 @@ Examples
 ========
 Consider the accessor class:
 
-.. literalinclude:: example.py
+.. literalinclude:: example/accessors.py
    :language: python
-   :lines: 32-68
+   :lines: 4-40
 
 for a class named :py:class:`Example`:
 
@@ -58,9 +58,9 @@ becomes:
 
 Methods on nested accessors can be documented, too:
 
-.. literalinclude:: example.py
+.. literalinclude:: example/accessors.py
    :language: python
-   :lines: 71-86
+   :lines: 43-59
 
 and
 

docs/requirements.txt

@@ -1,3 +1,3 @@
 packaging
-sphinx>=6
+sphinx>=6,<8.2
 sphinx_rtd_theme