My package has Google Earth Engine's Python API (package name: ee) as a dependency. Using sphinx to auto-generate documentation (for ultimate storage on readthedocs) works locally, however all of the submodules which import ee do not build on readthedocs.com. The error messages in the build log indicate that this is because ee requires authentication, and readthedocs cannot authenticate it.
Question: Is there a way to save my own authentication token for readthedocs so that my documentation can build properly for all of my submodules? For example in my setup.py file or in my readthedocs.yaml or environment.yaml files? Or is there another workaround to host my locally built documentation without having readthedocs try to run the code itself?
In Summary:
Desired behavior: All of the submodules show their functions and documentation automatically.
Actual behavior: Only the modules that don't import ee (currently waterpyk.calcs) have information in the docs, the rest are blank with titles only. I believe this is because ee requires authentication.
Reproducibility:
GitHub repo: https://github.com/erica-mccormick/waterpyk
Readthedocs webpage: https://waterpyk.readthedocs.io/en/latest/
Readthedocs build raw: https://readthedocs.org/api/v2/build/17058090.txt
For more information on ee's authentication, see here about the ee python installation:https://developers.google.com/earth-engine/guides/python_install. I am using conda for package management.
Here is a sample of the error (it continues on after this, repeating. See the raw link above):
WARNING: autodoc: failed to import module 'main' from module 'waterpyk'; the following exception was raised:
Traceback (most recent call last):
File "/home/docs/checkouts/readthedocs.org/user_builds/waterpyk/conda/latest/lib/python3.8/site-packages/ee/data.py", line 223, in get_persistent_credentials
return Credentials(None, **oauth.get_credentials_arguments())
File "/home/docs/checkouts/readthedocs.org/user_builds/waterpyk/conda/latest/lib/python3.8/site-packages/ee/oauth.py", line 72, in get_credentials_arguments
with open(get_credentials_path()) as creds:
FileNotFoundError: [Errno 2] No such file or directory: '/home/docs/.config/earthengine/credentials'
During handling of the above exception, another exception occurred:
Traceback (most recent call last):
File "/home/docs/checkouts/readthedocs.org/user_builds/waterpyk/conda/latest/lib/python3.8/site-packages/sphinx/ext/autodoc/importer.py", line 70, in import_module
return importlib.import_module(modname)
File "/home/docs/checkouts/readthedocs.org/user_builds/waterpyk/conda/latest/lib/python3.8/importlib/__init__.py", line 127, in import_module
return _bootstrap._gcd_import(name[level:], package, level)
File "<frozen importlib._bootstrap>", line 1014, in _gcd_import
File "<frozen importlib._bootstrap>", line 991, in _find_and_load
File "<frozen importlib._bootstrap>", line 975, in _find_and_load_unlocked
File "<frozen importlib._bootstrap>", line 671, in _load_unlocked
File "<frozen importlib._bootstrap_external>", line 843, in exec_module
File "<frozen importlib._bootstrap>", line 219, in _call_with_frames_removed
File "/home/docs/checkouts/readthedocs.org/user_builds/waterpyk/checkouts/latest/waterpyk/main.py", line 4, in <module>
ee.Initialize()
File "/home/docs/checkouts/readthedocs.org/user_builds/waterpyk/conda/latest/lib/python3.8/site-packages/ee/__init__.py", line 122, in Initialize
credentials = data.get_persistent_credentials()
File "/home/docs/checkouts/readthedocs.org/user_builds/waterpyk/conda/latest/lib/python3.8/site-packages/ee/data.py", line 225, in get_persistent_credentials
raise ee_exception.EEException(
ee.ee_exception.EEException: Please authorize access to your Earth Engine account by running
earthengine authenticate
in your command line, and then retry.
This is a use case for the autodoc_mock_imports option which is very handy "when some external dependencies are not met at build time and break the building process".
The problem is solved by adding the following line to conf.py:
autodoc_mock_imports = ["ee"]