Docs on ReadTheDocs

The default ReadTheDocs (RTD) configuration fails for ect-core because RTD tries to install our dependencies using pip (requirements.txt) but unfortunately the h5py package doesn't compile on their servers.

Therefore I am trying to activate the build using a RTD beta feature that uses a YAML configuration readthedocs.yml instead. See

• http://read-the-docs.readthedocs.io/en/latest/yaml-config.html

Using this allows for another RTD beta feature conda. See

• http://read-the-docs.readthedocs.io/en/latest/conda.html
• https://github.com/rtfd/readthedocs.org/issues/857

Following the docs, I created a new conda environment, see

• http://conda.pydata.org/docs/using/envs.html

then installed all required dependencies, and finally created a conda environment file environment.yml:

$ conda create --name ect
$ conda activate ect
$ conda install pytest pytest-cov
$ conda install xarray h5py numpy scipy matplotlib
$ conda install -c IOOS h5netcdf
$ conda env export > environment.yml

In the readthedocs.yml file, I then only have:

python:
    version: 3
    setup_py_install: true
conda:
    file: environment.yml

However, RTD still continues to use its default configuration instead of picking up my readthedocs.yml file:

python3 -mvirtualenv --no-site-packages /home/docs/checkouts/readthedocs.org/user_builds/ect-core/envs/latest
python /home/docs/checkouts/readthedocs.org/user_builds/ect-core/envs/latest/bin/pip install --use-wheel -U --cache-dir /home/docs/checkouts/readthedocs.org/user_builds/ect-core/.cache/pip sphinx==1.3.5 Pygments==2.1.3 setuptools==20.1.1 docutils==0.12 mkdocs==0.15.0 mock==1.0.1 pillow==2.6.1 git+https://github.com/rtfd/[email protected]#egg=readthedocs-sphinx-ext sphinx-rtd-theme==0.1.9 alabaster>=0.7,<0.8,!=0.7.5 commonmark==0.5.4 recommonmark==0.1.1
python /home/docs/checkouts/readthedocs.org/user_builds/ect-core/envs/latest/bin/pip install --exists-action=w --cache-dir /home/docs/checkouts/readthedocs.org/user_builds/ect-core/.cache/pip -r/home/docs/checkouts/readthedocs.org/user_builds/ect-core/checkouts/latest/requirements.txt

... and fails :(

• https://readthedocs.org/projects/ect-core/builds/4099230/

-- Norman