tox -e build_docs does not do the same as readthedocs CI

Description

I've been finding that tox -e build_docs will succeed locally but then a PR will fail on readthedocs. It also gives a number of warnings about poorly constrained fits, and a non-fatal error about the absence of dask.

Expected behavior

We should make sure the setup is such that readthedocs and build_docs do the same thing, and no unnecessary warnings are raised. It may still make sense to have a not-so-strict version (say, tox -e docs) as well.

How to Reproduce

tox -e build_docs

WARNING: The fit may be unsuccessful; check: meInfoBase .. api/astropy.units.DecibelUnit
    The maximum number of function evaluations is exceeded. [astropy.modeling.fitting]
reading sources... [100%] wcs/reference_api .. whatsnew/index
/home/mhvk/data/mhvk/packages/astropy/docs/modeling/parallel-fitting.rst:169: WARNING: Exception occurred in plotting parallel-fitting-10
 from /home/mhvk/data/mhvk/packages/astropy/docs/modeling/parallel-fitting.rst:
Traceback (most recent call last):
  File "/home/mhvk/data/mhvk/packages/astropy/.tox/build_docs/lib/python3.12/site-packages/astropy/modeling/_fitting_parallel.py", line 338, in parallel_fit_dask
    import dask
ModuleNotFoundError: No module named 'dask'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/mhvk/data/mhvk/packages/astropy/.tox/build_docs/lib/python3.12/site-packages/matplotlib/sphinxext/plot_directive.py", line 552, in _run_code
    exec(code, ns)
  File "<string>", line 2, in <module>
  File "/home/mhvk/data/mhvk/packages/astropy/.tox/build_docs/lib/python3.12/site-packages/astropy/modeling/_fitting_parallel.py", line 341, in parallel_fit_dask
    raise ImportError("dask is required for this function")
ImportError: dask is required for this function [docutils]
/home/mhvk/data/mhvk/packages/astropy/docs/modeling/parallel-fitting.rst:207: WARNING: Exception occurred in plotting parallel-fitting-11
 from /home/mhvk/data/mhvk/packages/astropy/docs/modeling/parallel-fitting.rst:
Traceback (most recent call last):
  File "/home/mhvk/data/mhvk/packages/astropy/.tox/build_docs/lib/python3.12/site-packages/matplotlib/sphinxext/plot_directive.py", line 552, in _run_code
    exec(code, ns)
  File "<string>", line 4, in <module>
NameError: name 'model_fit' is not defined [docutils]
/home/mhvk/data/mhvk/packages/astropy/docs/modeling/parallel-fitting.rst:227: WARNING: Exception occurred in plotting parallel-fitting-12
 from /home/mhvk/data/mhvk/packages/astropy/docs/modeling/parallel-fitting.rst:
Traceback (most recent call last):
looking for now-outdated files... none found
  File "/home/mhvk/data/mhvk/packages/astropy/.tox/build_docs/lib/python3.12/site-packages/matplotlib/sphinxext/plot_directive.py", line 552, in _run_code
    exec(code, ns)
  File "<string>", line 1, in <module>
NameError: name 'model_fit' is not defined [docutils]
/home/mhvk/data/mhvk/packages/astropy/docs/modeling/parallel-fitting.rst:239: WARNING: Exception occurred in plotting parallel-fitting-13
 from /home/mhvk/data/mhvk/packages/astropy/docs/modeling/parallel-fitting.rst:
Traceback (most recent call last):
  File "/home/mhvk/data/mhvk/packages/astropy/.tox/build_docs/lib/python3.12/site-packages/astropy/modeling/_fitting_parallel.py", line 338, in parallel_fit_dask
    import dask
ModuleNotFoundError: No module named 'dask'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/mhvk/data/mhvk/packages/astropy/.tox/build_docs/lib/python3.12/site-packages/matplotlib/sphinxext/plot_directive.py", line 552, in _run_code
    exec(code, ns)
  File "<string>", line 2, in <module>
  File "/home/mhvk/data/mhvk/packages/astropy/.tox/build_docs/lib/python3.12/site-packages/astropy/modeling/_fitting_parallel.py", line 341, in parallel_fit_dask
    raise ImportError("dask is required for this function")
ImportError: dask is required for this function [docutils]
/home/mhvk/data/mhvk/packages/astropy/docs/modeling/parallel-fitting.rst:255: WARNING: Exception occurred in plotting parallel-fitting-14
 from /home/mhvk/data/mhvk/packages/astropy/docs/modeling/parallel-fitting.rst:
Traceback (most recent call last):
  File "/home/mhvk/data/mhvk/packages/astropy/.tox/build_docs/lib/python3.12/site-packages/matplotlib/sphinxext/plot_directive.py", line 552, in _run_code
    exec(code, ns)
  File "<string>", line 4, in <module>
NameError: name 'model_fit' is not defined [docutils]

Versions

import astropy
try:
    astropy.system_info()
except AttributeError:
    import platform; print(platform.platform())
    import sys; print("Python", sys.version)
    import astropy; print("astropy", astropy.__version__)
    import numpy; print("Numpy", numpy.__version__)
    import erfa; print("pyerfa", erfa.__version__)
    try:
        import scipy
        print("Scipy", scipy.__version__)
    except ImportError:
        print("Scipy not installed")
    try:
        import matplotlib
        print("Matplotlib", matplotlib.__version__)
    except ImportError:
        print("Matplotlib not installed")

# Paste the result here

I'm seeing all of the same errors and warnings. Additionally, I'm having another issue with parallel builds that just crash

Example traceback

# Traceback:
Traceback (most recent call last):
  File "/private/tmp/astropy/.tox/build_docs/lib/python3.12/site-packages/sphinx/cmd/build.py", line 337, in build_main
    app.build(args.force_all, args.filenames)
  File "/private/tmp/astropy/.tox/build_docs/lib/python3.12/site-packages/sphinx/application.py", line 378, in build
    self.builder.build_update()
  File "/private/tmp/astropy/.tox/build_docs/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 296, in build_update
    self.build(to_build,
  File "/private/tmp/astropy/.tox/build_docs/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 317, in build
    updated_docnames = set(self.read())
                           ^^^^^^^^^^^
  File "/private/tmp/astropy/.tox/build_docs/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 422, in read
    self._read_parallel(docnames, nproc=self.app.parallel)
  File "/private/tmp/astropy/.tox/build_docs/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 509, in _read_parallel
    tasks.join()
  File "/private/tmp/astropy/.tox/build_docs/lib/python3.12/site-packages/sphinx/util/parallel.py", line 107, in join
    if not self._join_one():
           ^^^^^^^^^^^^^^^^
  File "/private/tmp/astropy/.tox/build_docs/lib/python3.12/site-packages/sphinx/util/parallel.py", line 125, in _join_one
    exc, logs, result = pipe.recv()
                        ^^^^^^^^^^^
  File "/Users/clm/Library/Application Support/uv/python/cpython-3.12.6-macos-aarch64-none/lib/python3.12/multiprocessing/connection.py", line 250, in recv
    buf = self._recv_bytes()
          ^^^^^^^^^^^^^^^^^^
  File "/Users/clm/Library/Application Support/uv/python/cpython-3.12.6-macos-aarch64-none/lib/python3.12/multiprocessing/connection.py", line 430, in _recv_bytes
    buf = self._recv(4)
          ^^^^^^^^^^^^^
  File "/Users/clm/Library/Application Support/uv/python/cpython-3.12.6-macos-aarch64-none/lib/python3.12/multiprocessing/connection.py", line 399, in _recv
    raise EOFError
EOFError

which I'm able to work around with the following patch

diff --git a/tox.ini b/tox.ini
index 08c48276a0..e3adba49a5 100644
--- a/tox.ini
+++ b/tox.ini
@@ -137,7 +137,7 @@ description = invoke sphinx-build to build the HTML docs
 extras = docs
 commands =
     {list_dependencies_command}
-    sphinx-build -b html . _build/html {posargs:-j auto}
+    sphinx-build -b html . _build/html # {posargs:-j auto}

 [testenv:linkcheck]
 changedir = docs

Coincidentally, I think I can make all the warnings and errors we're both seeing with this patch

diff --git a/tox.ini b/tox.ini
index 08c48276a0..0b38048029 100644
--- a/tox.ini
+++ b/tox.ini
@@ -116,6 +116,7 @@ extras =
     recdeps: test_all
     alldeps: all
     alldeps: test_all
+    build_docs: all

 commands =
     {list_dependencies_command}

I would argue that tox isn't necessary at all to build docs with. Not that hard to type cd docs; make html (or the Windows variant). That is what RTD is doing anyway. If I can have it my way, I would remove build_docs from tox entirely but I tried it once a long time ago and encountered resistance.

I think it is similar with testing, tox doesn't really add much except setting up the right virtual environment. But this is quite useful!

Agreed with Marten. In my own experience, I very often need to (re)create fresh virtual environments to run astropy's test suite in controled conditions, and it's nice that tox is there to do the heavy lifting in many common cases. Building docs is a task that requires many additional dependencies that do not belong in a minimal test env, so it seems to fit tox's mission pretty well and I would prefer having tox -e build_docs work (and be tested) than removing it. Futhermore it seems we can get the "tested" part essentially for free if we tweak RTD to actually exercise it. I don't see clear downsides to this.

I guess an experimental PR never hurts (except the wallet a little bit).

Navigation Menu

Repository navigation

tox -e build_docs does not do the same as readthedocs CI #17052

Description

Expected behavior

How to Reproduce

Versions

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

tox -e build_docs does not do the same as readthedocs CI #17052

Description

Description

Expected behavior

How to Reproduce

Versions

Activity

neutrinoceros commented on Sep 22, 2024

pllim commented on Sep 23, 2024

mhvk commented on Sep 23, 2024

neutrinoceros commented on Sep 24, 2024

pllim commented on Sep 24, 2024

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions