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 on Ubuntu (RDT uses 64bit Linux servers), 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 numpydoc
$ 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

If I don't remove h5netcdf from environment.yml the build will fail, because the latter can obviously not be told to use a specific channel (TBC!).

Here is the documentation link:

• http://ect-core.readthedocs.io/en/latest/

-- Norman