tox -e build_docs does not do the same as readthedocs CI
- 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
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