RC_v1.5.0 API docs broken

[freemansw1]

https://tobac.readthedocs.io/en/rc_v1.5.0/tobac.html

[w-k-jones]

Just went back through the pull requests for RC_v1.5.0, the docs breaking occurs with #259 and #127

Which is odd because as far as I can see neither modifies the API reference section of the docs...

Could it be something to do with the changes to the utils structure?

[fsenf]

autodoc seems to run into an import error:

...
WARNING: autodoc: failed to import module 'analysis' from module 'tobac'; the following exception was raised:
...

[fsenf]

OK, now I read further:

...
  File "/home/docs/checkouts/readthedocs.org/user_builds/tobac/checkouts/293/tobac/utils/periodic_boundaries.py", line 261, in <module>
    high: float = 2 * np.pi,
TypeError: unsupported operand type(s) for *: 'int' and '_MockObject'

The problem comes with the fact that we mock all python libs like numpy and this appear to be in conflict with the variable definition using type hints.

@freemansw1 : You could try out float = 2. * np.pi ...

[JuliaKukulies]

I tried that @fsenf @freemansw1 and the API looks fine when I locally build the page, but it does not seem to do the job (https://tobac--303.org.readthedocs.build/en/303/tobac.html ).

The pull requests that have not merged in the period boundary changes seem to work, e.g.
https://tobac--281.org.readthedocs.build/en/281/tobac.html#tobac-utils-general-modules And we had already changed the utils structure in these, so I am not sure if it is really related to the utils submodules @w-k-jones.

We forgot indeed to add tobac.utils.periodic_boundaries and tobac.utils.internal to doc/tobac.rst but this does not fix it either :(

[fsenf]

Hi,

I was able to reproduce the bug in a clean setup using the description here: https://github.com/tobac-project/tobac-tutorials/blob/main/docs/Testing-Sphinx-based-Rendering.md up to the end of Section 1 (replacing tobac-tutorials with tobac).

Some additional commands:

 pip install sphinx_rtd_theme
sphinx-build -b html doc doc/_build/html

Last command also fails with

...
  File "/tmp/website-testing/tobac/tobac/utils/periodic_boundaries.py", line 261, in <module>
    high: float = 2 * np.pi,
TypeError: unsupported operand type(s) for *: 'int' and 'pi'
...

[fsenf]

float = 2. * np.pi does not help.

[fsenf]

SOLUTION:

The API doc come back again if we do not mock numpy:

> git diff
diff --git a/doc/conf.py b/doc/conf.py
index 0f5e48e..e897fd7 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -43,7 +43,7 @@ def setup(app):
 # This should include all modules used in tobac. These are dummy imports,
 # but should include both required and optional dependencies.
 autodoc_mock_imports = [
-    "numpy",
+#    "numpy",
     "scipy",
     "scikit-image",
     "pandas",
diff --git a/doc/requirements.txt b/doc/requirements.txt
index 82f69f7..6ba789a 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -1,2 +1,3 @@
 ipykernel
 nbsphinx
+numpy

[fsenf]

@freemansw1 @w-k-jones @JuliaKukulies : Can we afford to install numpy at each readthedocs re-rendering? I think, yes. What do you think?

[w-k-jones]

Would it be possible to switch to using math.pi for the default value instead? That way we should be able to keep numpy as a mock

[fsenf]

Yes, this works!

But

1. one need to input an import that is barely used import math
2. the internals of the function use np.pi which would be inconsistent with the opt. arg definition

[freemansw1]

Resolved with #305