From 3517a22a42448ef6aab61b5a50ea4043cf5ca7c6 Mon Sep 17 00:00:00 2001
From: Bastian Krause <bst@pengutronix.de>
Date: Tue, 8 Aug 2023 12:45:39 +0200
Subject: [PATCH] pyproject.toml: require Sphinx>=2.0.0 for doc feature

readthedocs installs Python package dependencies like this:

  pip install --upgrade --no-cache-dir pip setuptools
  pip install --upgrade --no-cache-dir pillow mock==1.0.1 alabaster>=0.7,<0.8,!=0.7.5 commonmark==0.9.1 recommonmark==0.5.0 sphinx<2 sphinx-rtd-theme<0.5 readthedocs-sphinx-ext<2.3 jinja2<3.1.0
  pip install --upgrade --upgrade-strategy only-if-needed --no-cache-dir .[doc]

Until recently --upgrade-strategy was specified as `eager`, but now
`only-if-needed` [1]. This results in Sphinx 1.8.6 being used.

This becomes an issue since Sphinx is not required directly by labgrid,
but via sphinx_rtd_theme which loosely requires `sphinx >=1.6,<8` [2].
This results in this readthedocs build error:

  Exception occurred:
    File "[...]/labgrid/venv-rtd-debugging/lib/python3.11/site-packages/sphinx/ext/autodoc/__init__.py", line 82, in members_option
      return [x.strip() for x in arg.split(',')]
                                 ^^^^^^^^^
  AttributeError: 'bool' object has no attribute 'split'

We could make this work with Sphinx<2.0.0 [3]:

  --- a/doc/conf.py
  +++ b/doc/conf.py
  @@ -179,7 +179,7 @@ texinfo_documents = [

   autodoc_member_order = 'bysource'
   autodoc_default_options = {
  -        'special-members': True,
  +        'special-members': None,
   }
   autodoc_mock_imports = ['onewire',
                           'txaio',

But even with this, another errors and several warnings occur:

  WARNING: Sphinx 1.x is deprecated with sphinx_rtd_theme, update to Sphinx 2.x or greater
  WARNING: 'html4_writer' is deprecated with sphinx_rtd_theme

  [...]/labgrid/venv-rtd-debugging/lib/python3.11/site-packages/sphinx/util/nodes.py:94: FutureWarning:
     The iterable returned by Node.traverse()
     will become an iterator instead of a list in Docutils > 0.16.
    for classifier in reversed(node.parent.traverse(nodes.classifier)):
  [...]/labgrid/doc/getting_started.rst:393: WARNING: Error in "code-block" directive:
  1 argument(s) required, 0 supplied.
  Exception occurred:
    File "[...]/labgrid/venv-rtd-debugging/lib/python3.11/site-packages/sphinx/ext/napoleon/docstring.py", line 123, in __init__
      elif isinstance(obj, collections.Callable):  # type: ignore
                           ^^^^^^^^^^^^^^^^^^^^
  AttributeError: module 'collections' has no attribute 'Callable'

It's not worth the effort to keep this backwards compatible, so simply
require Sphinx>=2.0.0 in labgrid directly.

[1] https://github.com/readthedocs/readthedocs.org/pull/10560
[2] https://github.com/readthedocs/sphinx_rtd_theme/blob/b5833585b25358be94918f13c50530e3e9237e7e/setup.cfg
[3] https://github.com/sphinx-doc/sphinx/issues/5459

Signed-off-by: Bastian Krause <bst@pengutronix.de>
---
 pyproject.toml | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/pyproject.toml b/pyproject.toml
index 4b1981da3..577bce655 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -51,7 +51,10 @@ dynamic = ["version"]  # via setuptools_scm
 "Bug Tracker" = "https://github.com/labgrid-project/labgrid/issues"
 
 [project.optional-dependencies]
-doc = ["sphinx_rtd_theme>=1.0.0"]
+doc = [
+    "sphinx_rtd_theme>=1.0.0",
+    "Sphinx>=2.0.0",
+]
 docker = ["docker>=5.0.2"]
 graph = ["graphviz>=0.17.0"]
 kasa = ["python-kasa>=0.4.0"]
@@ -80,6 +83,7 @@ dev = [
     # references to other optional dependency groups
     # labgrid[doc]
     "sphinx_rtd_theme>=1.0.0",
+    "Sphinx>=2.0.0",
 
     # labgrid[docker]
     "docker>=5.0.2",