local docs build "failure"

[jGaboardi]

The last time the build_docs.yaml action was run prior to these failures was in 2023-01 with the output being the current docs site --> spaghetti==1.7.2. Here we can see that the spaghetti.Network class¹ and {savenetwork,loadnetwork} methods² API references are fully generated without error. However, starting from #726 I have not been able to get the docs to build properly locally, specifically having trouble with the parts just mentioned. What I am seeing locally is no spaghetti.Network API reference being produced³ and the {savenetwork,loadnetwork} methods not being generated⁴ with a warning from autosummary being thrown⁵.

It may or may not be related to setuptools_scm, sphinx, or something else entirely. Been trying to debug it for several weeks, but still seem to be no closer. The last time docs build proper we were still on versioneer, now we have switched to setuptools_scm=7.1.0 FWIW. I have seen this problem locally with sphinx={6.1.3, 6.2.1, 7.0.1}. It's probably something simple that I'm overlooking, but at this point I'm confounded.

Any set of eyes or an idea to look into would be super appreciated. @martinfleis, @weikang9009, @knaaptime, @gegen07

Footnotes

1. https://pysal.org/spaghetti/generated/spaghetti.Network.html#spaghetti.Network ↩

2. https://pysal.org/spaghetti/api.html#save-and-load-a-network ↩

3. ↩

4. ↩

5. warning

   /PATH/spaghetti/docs/api.rst:35: WARNING: autosummary: failed to import spaghetti.Network.savenetwork.
   Possible hints:
   * AttributeError: module 'spaghetti.Network' has no attribute 'savenetwork'
   * ModuleNotFoundError: No module named 'spaghetti.spaghetti'
   * ModuleNotFoundError: No module named 'spaghetti.Network.savenetwork'; 'spaghetti.Network' is not a package
   * ImportError: 
   * AttributeError: module 'spaghetti' has no attribute 'spaghetti'
   /PATH/spaghetti/docs/api.rst:35: WARNING: autosummary: failed to import spaghetti.Network.loadnetwork.
   Possible hints:
   * AttributeError: module 'spaghetti' has no attribute 'spaghetti'
   * ModuleNotFoundError: No module named 'spaghetti.spaghetti'
   * ModuleNotFoundError: No module named 'spaghetti.Network.loadnetwork'; 'spaghetti.Network' is not a package
   * ImportError: 
   * AttributeError: module 'spaghetti.Network' has no attribute 'loadnetwork'
   

   ↩

[martinfleis]

It is related to a version of Python. It works if you have 3.9 in the same environment, it fails under 3.11. Not sure what has changed though.

[jGaboardi]

It is related to a version of Python. It works if you have 3.9 in the same environment, it fails under 3.11. Not sure what has changed though.

Oh wow... Where would we report this?

[martinfleis]

I am not certain it is a bug, on Python side. It may be some behaviour change we need to adapt to.

[jGaboardi]

Closing for now with viable solution in #733. Can revisit and open later if needed.

[jGaboardi]

xref: mcmtroffaes/sphinxcontrib-bibtex#284