astropy / astropy/astropy

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

Open
#17,052 5 comments 1 reaction 0 assignees View on GitHub
Bug Docs testing
Dominant language
Python
Stars
5.3k
Forks
2.2k
Avg merge
1d 18h
Merged PRs (30d)
74

Description

### 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 "", line 2, in
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 "", line 4, in
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 "", line 1, in
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 "", line 2, in
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 "", line 4, in
NameError: name 'model_fit' is not defined [docutils]
```

### Versions

```python
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
```

Contributor guide

Open the contributing guide

Research direction

Start by comparing the tox -e build_docs environment with the readthedocs CI configuration, then run tox -e build_docs and inspect docs/modeling/parallel-fitting.rst alongside the reported warnings. Done means both builds use the same setup and the unnecessary fit, missing-dask, and plotting warnings no longer occur.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
build-system, ci-cd, documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.