Broken Sphinx links in doc page on contributing to docs

[rdrussotto]

The doc page on contributing to the docs has two broken links to sphinx.pocoo.org. The content has been moved to sphinx-doc.org. The doc page should be updated to reflect this.

Also, it would be useful to explicitly specify that you need to install sphinx, nbsphinx, and all the nbsphinx prerequesites in order to build the docs, as well as installing any additional missing packages that cause errors during the doc build process (I had to install cfgrib and h5netcdf).

[keewis]

Did you use

conda env create -f ci/requirements/doc.yml

for building a documentation environment? conda should automatically install all the dependencies for you. Also, at least cfgrib is a new requirement for building the docs and should be in doc.yml on master.

When I last tried to use virtualenv / pip instead of conda, building the documentation failed because cartopy is not on pypi / has no wheels, so that way to install might be hard. I think we should try to fix that.

Just to make sure: the documentation you linked to is not for master but for the last release, the documentation for master is here.

Links: thanks, do you want to send in a PR fixing that?

[rdrussotto]

Yes, I used conda env create -f ci/requirements/doc.yml to make the documentation environment. Thanks for clarifying about the master documentation.

I'll do a PR for the links tomorrow.

[keewis]

that's strange, then. Could you retry creating a new environment and post the output of conda list?

I'll do a PR for the links tomorrow.

👍

[rdrussotto]

I removed and re-created the xarray-docs environment. Output of conda list below. Sphinx, nbsphinx, and h5netcdf aren't there, although cfgrib is. It did say sphinx-2.3.1 was being downloaded and extracted.

Could this problem have something to do with me having cloned an old fork of xarray from like 6 months ago? (I was afraid to delete the fork and make a new fork for fear of losing the record of what I did in the last PR). I did use git fetch upstream and
git rebase upstream/master, though, before creating the environments, and it seems to have worked in terms of pulling in the latest commits since they were visible in git log.

# packages in environment at /home/russotto/miniconda3/envs/xarray-tests:
#
# Name                    Version                   Build  Channel
_libgcc_mutex             0.1                 conda_forge    conda-forge
_openmp_mutex             4.5                       0_gnu    conda-forge
affine                    2.3.0                      py_0    conda-forge
antlr-python-runtime      4.7.2                 py36_1001    conda-forge
appdirs                   1.4.3                      py_1    conda-forge
asciitree                 0.3.3                      py_2    conda-forge
attrs                     19.3.0                     py_0    conda-forge
beautifulsoup4            4.8.2                    py36_0    conda-forge
black                     19.10b0                  py36_0    conda-forge
bokeh                     1.4.0                    py36_0    conda-forge
boost-cpp                 1.70.0               h8e57a91_2    conda-forge
boto3                     1.11.5                     py_0    conda-forge
botocore                  1.14.5                     py_0    conda-forge
bottleneck                1.3.1            py36hc1659b7_0    conda-forge
bzip2                     1.0.8                h516909a_2    conda-forge
ca-certificates           2019.11.28           hecc5488_0    conda-forge
cairo                     1.16.0            hfb77d84_1002    conda-forge
cartopy                   0.17.0          py36h423102d_1009    conda-forge
cdat_info                 8.2                        py_6    conda-forge
cdms2                     3.1.4                    pypi_0    pypi
cdtime                    3.1.2            py36h1ac8016_8    conda-forge
certifi                   2019.11.28               py36_0    conda-forge
cf-units                  2.1.3            py36hc1659b7_0    conda-forge
cffi                      1.13.2           py36h8022711_0    conda-forge
cfgrib                    0.9.7.6                    py_0    conda-forge
cfitsio                   3.470                hb60a0a2_2    conda-forge
cftime                    1.0.4.2          py36hc1659b7_0    conda-forge
chardet                   3.0.4                 py36_1003    conda-forge
click                     7.0                        py_0    conda-forge
click-plugins             1.1.1                      py_0    conda-forge
cligj                     0.5.0                      py_0    conda-forge
cloudpickle               1.2.2                      py_1    conda-forge
coverage                  5.0.3            py36h516909a_0    conda-forge
coveralls                 1.10.0                     py_0    conda-forge
cryptography              2.8              py36h72c5cf5_1    conda-forge
curl                      7.65.3               hf8cf82a_0    conda-forge
cycler                    0.10.0                     py_2    conda-forge
cytoolz                   0.10.1           py36h516909a_0    conda-forge
dask                      2.9.2                      py_0    conda-forge
dask-core                 2.9.2                      py_0    conda-forge
dataclasses               0.7                      py36_0    conda-forge
dbus                      1.13.6               he372182_0    conda-forge
decorator                 4.4.1                      py_0    conda-forge
distarray                 2.12.2                     py_1    conda-forge
distributed               2.9.3                      py_0    conda-forge
docopt                    0.6.2                      py_1    conda-forge
docutils                  0.15.2                   py36_0    conda-forge
eccodes                   2.16.0               h0533f67_0    conda-forge
entrypoints               0.3                   py36_1000    conda-forge
esmf                      8.0.0           nompi_he6d0a24_4    conda-forge
esmpy                     8.0.0           nompi_py36hf0e99fa_1    conda-forge
expat                     2.2.5             he1b5a44_1004    conda-forge
fasteners                 0.14.1                     py_3    conda-forge
flake8                    3.7.9                    py36_0    conda-forge
fontconfig                2.13.1            h86ecdb6_1001    conda-forge
freetype                  2.10.0               he983fc9_1    conda-forge
freexl                    1.0.5             h14c3975_1002    conda-forge
fsspec                    0.6.2                      py_0    conda-forge
future                    0.18.2                   py36_0    conda-forge
g2clib                    1.6.0                hf3f1b0b_9    conda-forge
geos                      3.8.0                he1b5a44_0    conda-forge
geotiff                   1.5.1                hbd99317_7    conda-forge
gettext                   0.19.8.1          hc5be6a0_1002    conda-forge
giflib                    5.2.1                h516909a_1    conda-forge
glib                      2.58.3          py36h6f030ca_1002    conda-forge
gst-plugins-base          1.14.5               h0935bb2_0    conda-forge
gstreamer                 1.14.5               h36ae1b5_0    conda-forge
h5netcdf                  0.7.4                      py_0    conda-forge
h5py                      2.10.0          nompi_py36h513d04c_101    conda-forge
hdf4                      4.2.13            hf30be14_1003    conda-forge
hdf5                      1.10.5          nompi_h3c11f04_1104    conda-forge
hdfeos2                   2.20              h64bfcee_1000    conda-forge
hdfeos5                   5.1.16               h8b6279f_5    conda-forge
heapdict                  1.0.1                      py_0    conda-forge
hypothesis                5.2.0                      py_0    conda-forge
icu                       64.2                 he1b5a44_1    conda-forge
idna                      2.8                   py36_1000    conda-forge
importlib_metadata        1.4.0                    py36_0    conda-forge
ipython_genutils          0.2.0                      py_1    conda-forge
iris                      2.2.0                 py36_1003    conda-forge
jasper                    1.900.1           h07fcdf6_1006    conda-forge
jinja2                    2.10.3                     py_0    conda-forge
jmespath                  0.9.4                      py_0    conda-forge
jpeg                      9c                h14c3975_1001    conda-forge
json-c                    0.13.1            h14c3975_1001    conda-forge
jsonschema                3.2.0                    py36_0    conda-forge
jupyter_core              4.6.1                    py36_0    conda-forge
kealib                    1.4.10            h58c409b_1005    conda-forge
kiwisolver                1.1.0            py36hc9558a2_0    conda-forge
krb5                      1.16.4               h2fd8d38_0    conda-forge
lazy-object-proxy         1.4.3            py36h516909a_0    conda-forge
libaec                    1.0.4                hf484d3e_0    conda-forge
libblas                   3.8.0               11_openblas    conda-forge
libcblas                  3.8.0               11_openblas    conda-forge
libcdms                   3.1.2                ha54dda3_8    conda-forge
libcf                     1.0.3            py36hdee1361_5    conda-forge
libclang                  9.0.1           default_hde54327_0    conda-forge
libcurl                   7.65.3               hda55be3_0    conda-forge
libdap4                   3.20.4               hd3bb157_0    conda-forge
libdrs                    3.1.2                h9b7ed86_9    conda-forge
libdrs_f                  3.1.2                h322d3c2_5    conda-forge
libedit                   3.1.20170329      hf8c457e_1001    conda-forge
libffi                    3.2.1             he1b5a44_1006    conda-forge
libgcc-ng                 9.2.0                h24d8f2e_2    conda-forge
libgdal                   3.0.2                hbe56659_7    conda-forge
libgfortran-ng            7.3.0                hdf63c60_4    conda-forge
libgomp                   9.2.0                h24d8f2e_2    conda-forge
libiconv                  1.15              h516909a_1005    conda-forge
libkml                    1.3.0             h4fcabce_1010    conda-forge
liblapack                 3.8.0               11_openblas    conda-forge
libllvm8                  8.0.1                hc9558a2_0    conda-forge
libllvm9                  9.0.1                hc9558a2_0    conda-forge
libnetcdf                 4.7.3           nompi_h94020b1_100    conda-forge
libopenblas               0.3.6                h6e990d7_6    conda-forge
libpng                    1.6.37               hed695b0_0    conda-forge
libpq                     12.1                 hd9ab2ff_0    conda-forge
libspatialite             4.3.0a            h343d7df_1033    conda-forge
libssh2                   1.8.2                h22169c7_2    conda-forge
libstdcxx-ng              9.2.0                hdf63c60_2    conda-forge
libtiff                   4.1.0                hc3755c2_3    conda-forge
libuuid                   2.32.1            h14c3975_1000    conda-forge
libwebp                   1.0.2                h56121f0_5    conda-forge
libxcb                    1.13              h14c3975_1002    conda-forge
libxkbcommon              0.9.1                hebb1f50_0    conda-forge
libxml2                   2.9.10               hee79883_0    conda-forge
libxslt                   1.1.33               h31b3aaa_0    conda-forge
llvmlite                  0.31.0           py36h8b12597_0    conda-forge
locket                    0.2.0                      py_2    conda-forge
lxml                      4.4.2            py36h7ec2d77_0    conda-forge
lz4-c                     1.8.3             he1b5a44_1001    conda-forge
markupsafe                1.1.1            py36h516909a_0    conda-forge
matplotlib                3.1.2                    py36_1    conda-forge
matplotlib-base           3.1.2            py36h250f245_1    conda-forge
mccabe                    0.6.1                      py_1    conda-forge
mechanicalsoup            0.12.0                     py_0    conda-forge
monotonic                 1.5                        py_0    conda-forge
more-itertools            8.1.0                      py_0    conda-forge
msgpack-python            0.6.2            py36hc9558a2_0    conda-forge
mypy                      0.761                      py_0    conda-forge
mypy_extensions           0.4.3                    py36_0    conda-forge
nbformat                  5.0.3                      py_0    conda-forge
nc-time-axis              1.2.0                      py_0    conda-forge
ncurses                   6.1               hf484d3e_1002    conda-forge
netcdf-fortran            4.5.2           nompi_h09cde99_103    conda-forge
netcdf4                   1.5.3           nompi_py36hd35fb8e_102    conda-forge
nspr                      4.24                 he1b5a44_0    conda-forge
nss                       3.47                 he751ad9_0    conda-forge
numba                     0.47.0           py36hb3f55d8_0    conda-forge
numbagg                   0.1                      pypi_0    pypi
numcodecs                 0.6.4            py36he1b5a44_0    conda-forge
numpy                     1.17.5           py36h95a1406_0    conda-forge
olefile                   0.46                       py_0    conda-forge
openblas                  0.3.6                h6e990d7_6    conda-forge
openjpeg                  2.3.1                h981e76c_3    conda-forge
openssl                   1.1.1d               h516909a_0    conda-forge
owslib                    0.19.0                     py_2    conda-forge
packaging                 20.0                       py_0    conda-forge
pandas                    0.25.3           py36hb3f55d8_0    conda-forge
partd                     1.1.0                      py_0    conda-forge
pathspec                  0.7.0                      py_0    conda-forge
patsy                     0.5.1                      py_0    conda-forge
pcre                      8.43                 he1b5a44_0    conda-forge
pillow                    7.0.0            py36hefe7db6_0    conda-forge
pint                      0.10.1                     py_0    conda-forge
pip                       19.3.1                   py36_0    conda-forge
pixman                    0.38.0            h516909a_1003    conda-forge
pluggy                    0.12.0                     py_0    conda-forge
poppler                   0.67.0               h14e79db_8    conda-forge
poppler-data              0.4.9                         1    conda-forge
postgresql                12.1                 hc63931a_0    conda-forge
proj                      6.2.1                hc80f0dc_0    conda-forge
pseudonetcdf              3.1.0                      py_0    conda-forge
psutil                    5.6.7            py36h516909a_0    conda-forge
pthread-stubs             0.4               h14c3975_1001    conda-forge
py                        1.8.1                      py_0    conda-forge
pycodestyle               2.5.0                      py_0    conda-forge
pycparser                 2.19                     py36_1    conda-forge
pydap                     3.2.2                 py36_1000    conda-forge
pyepsg                    0.4.0                      py_0    conda-forge
pyflakes                  2.1.1                      py_0    conda-forge
pykdtree                  1.3.1           py36hc1659b7_1002    conda-forge
pyke                      1.1.1                 py36_1001    conda-forge
pynio                     1.5.5            py36h793c684_8    conda-forge
pyopenssl                 19.1.0                   py36_0    conda-forge
pyparsing                 2.4.6                      py_0    conda-forge
pyproj                    2.4.2.post1      py36h12732c1_0    conda-forge
pyqt                      5.12.3           py36hcca6a23_1    conda-forge
pyqt5-sip                 4.19.18                  pypi_0    pypi
pyqtwebengine             5.12.1                   pypi_0    pypi
pyrsistent                0.15.7           py36h516909a_0    conda-forge
pyshp                     2.1.0                      py_0    conda-forge
pysocks                   1.7.1                    py36_0    conda-forge
pytest                    5.3.3                    py36_0    conda-forge
pytest-cov                2.8.1                      py_0    conda-forge
pytest-env                0.6.2                      py_0    conda-forge
python                    3.6.7             h357f687_1006    conda-forge
python-dateutil           2.8.1                      py_0    conda-forge
pytz                      2019.3                     py_0    conda-forge
pyyaml                    5.3              py36h516909a_0    conda-forge
qt                        5.12.5               hd8c4c69_1    conda-forge
rasterio                  1.1.2            py36h900e953_0    conda-forge
readline                  8.0                  hf8c457e_0    conda-forge
regex                     2020.1.8         py36h516909a_0    conda-forge
regrid2                   3.1.4                    pypi_0    pypi
requests                  2.22.0                   py36_1    conda-forge
s3transfer                0.3.1                    py36_0    conda-forge
scipy                     1.4.1            py36h921218d_0    conda-forge
seaborn                   0.9.0                      py_2    conda-forge
setuptools                45.1.0                   py36_0    conda-forge
shapely                   1.6.4           py36h5d51c17_1007    conda-forge
six                       1.14.0                   py36_0    conda-forge
snuggs                    1.4.7                      py_0    conda-forge
sortedcontainers          2.1.0                      py_0    conda-forge
soupsieve                 1.9.4                    py36_0    conda-forge
sparse                    0.8.0                      py_0    conda-forge
sqlite                    3.30.1               hcee41ef_0    conda-forge
statsmodels               0.10.2           py36hc1659b7_0    conda-forge
tbb                       2018.0.5             h2d50403_0    conda-forge
tblib                     1.6.0                      py_0    conda-forge
tiledb                    1.7.0                hcde45ca_2    conda-forge
tk                        8.6.10               hed695b0_0    conda-forge
toml                      0.10.0                     py_0    conda-forge
toolz                     0.10.0                     py_0    conda-forge
tornado                   6.0.3            py36h516909a_0    conda-forge
traitlets                 4.3.3                    py36_0    conda-forge
typed-ast                 1.4.1            py36h516909a_0    conda-forge
typing_extensions         3.7.4.1                  py36_0    conda-forge
tzcode                    2019a             h516909a_1002    conda-forge
udunits2                  2.2.27.6          h4e0c4b3_1001    conda-forge
urllib3                   1.25.7                   py36_0    conda-forge
wcwidth                   0.1.8                      py_0    conda-forge
webob                     1.8.5                      py_0    conda-forge
wheel                     0.33.6                   py36_0    conda-forge
xarray                    0.14.1+57.gc32e58b           dev_0    <develop>
xerces-c                  3.2.2             h8412b87_1004    conda-forge
xorg-kbproto              1.0.7             h14c3975_1002    conda-forge
xorg-libice               1.0.10               h516909a_0    conda-forge
xorg-libsm                1.2.3             h84519dc_1000    conda-forge
xorg-libx11               1.6.9                h516909a_0    conda-forge
xorg-libxau               1.0.9                h14c3975_0    conda-forge
xorg-libxdmcp             1.1.3                h516909a_0    conda-forge
xorg-libxext              1.3.4                h516909a_0    conda-forge
xorg-libxrender           0.9.10            h516909a_1002    conda-forge
xorg-renderproto          0.11.1            h14c3975_1002    conda-forge
xorg-xextproto            7.3.0             h14c3975_1002    conda-forge
xorg-xproto               7.0.31            h14c3975_1007    conda-forge
xz                        5.2.4             h14c3975_1001    conda-forge
yaml                      0.2.2                h516909a_1    conda-forge
zarr                      2.4.0                      py_0    conda-forge
zict                      1.0.0                      py_0    conda-forge
zipp                      1.0.0                      py_0    conda-forge
zlib                      1.2.11            h516909a_1006    conda-forge
zstd                      1.4.4                h3b9ef0a_1    conda-forge

[keewis]

are you sure you activated the right environment? There are some packages from pypi that should not have been installed if the content of doc.yml is:

xarray/ci/requirements/doc.yml

Lines 1 to 25 in aa0f963

	name: xarray-docs
	channels:
	# Don't change to pkgs/main, as it causes random timeouts in readthedocs
	- conda-forge
	dependencies:
	- python=3.7
	- bottleneck
	- cartopy
	- cfgrib
	- h5netcdf
	- ipykernel
	- ipython
	- iris
	- jupyter_client
	- nbsphinx
	- netcdf4
	- numba
	- numpy
	- numpydoc
	- pandas<0.25 # Hack around https://github.com/pydata/xarray/issues/3369
	- rasterio
	- seaborn
	- sphinx
	- sphinx_rtd_theme
	- zarr

Also, you don't need to delete the environment, using

$ conda env create -n xarray-docs-test -f ci/requirements/doc.yml
$ conda activate xarray-docs-test
$ # try building the documentation
$ conda deactivate xarray-docs-test
$ conda env remove -n xarray-docs-test

should work, too