Resolve the version issues on RTD (#3589)

* add the project root to PYTHONPATH and sys.path

* don't install the package

* update the requirements for the documentation environment

so we definitely trigger the version collision.

* comment on the reasons for the sys.path and os.environ modifications

Author: keewis

ci/requirements/doc.yml

@@ -6,7 +6,7 @@ dependencies:
   - python=3.7
   - bottleneck
   - cartopy
-  - eccodes
+  - cfgrib
   - h5netcdf
   - ipykernel
   - ipython
@@ -21,8 +21,5 @@ dependencies:
   - seaborn
   - sphinx
   - sphinx_rtd_theme
+  - xarray
   - zarr
-  - pip
-  - pip:
-    - cfgrib
-

doc/conf.py

@@ -15,10 +15,16 @@
 
 import datetime
 import os
+import pathlib
 import subprocess
 import sys
 from contextlib import suppress
 
+# make sure the source version is preferred (#3567)
+root = pathlib.Path(__file__).absolute().parent.parent
+os.environ["PYTHONPATH"] = str(root)
+sys.path.insert(0, str(root))
+
 import xarray
 
 allowed_failures = set()

readthedocs.yml

@@ -4,5 +4,5 @@ conda:
     file: ci/requirements/doc.yml
 python:
     version: 3.7
-    setup_py_install: true
+    setup_py_install: false
 formats: []