Fix RTD build

[NoraLoose]

Looks like I made some progress. The RTD build still fails, but it got a bit further. It can now import cstar, but has a problem with an os.environ key:

  File "/home/docs/checkouts/readthedocs.org/user_builds/c-star/checkouts/79/cstar/base/environment.py", line 156, in <module>
    os.environ["MPIHOME"] = os.environ["CONDA_PREFIX"]
                            ~~~~~~~~~~^^^^^^^^^^^^^^^^
  File "<frozen os>", line 714, in __getitem__
KeyError: 'CONDA_PREFIX'

https://readthedocs.org/projects/c-star/builds/25623421/

@dafyddstephenson you know what's going on?

[dafyddstephenson]

yeah this is setting the environment variable MPIHOME used by ROMS in the case that the user is on a generic x86 machine (as whatever is doing the importing probably is). In this case the MPI library will be accessible from the conda environment top level /wherever/envs/cstar_env/ which is stored in the system CONDA_PREFIX environment variable, hence os.environ["MPIHOME"] = os.environ["CONDA_PREFIX"]. If the CONDA_PREFIX variable isn't available, it's telling me the conda environment hasn't been activated 🤔

[NoraLoose]

ReadTheDocs (RTD) does not have direct access to environment variables like CONDA_PREFIX in the same way a local Conda environment would. RTD uses its own build environment, which typically relies on a virtualenv or a pip-based environment, not Conda.

[dafyddstephenson]

not sure if there's a clear way around this as we can't install non-python dependencies like netcdf-fortran with pip... damn. So you're not using conda at all? (e.g. with the ci/environment.yml file?)

[NoraLoose]

I do use the ci/environment.yml file. But here is what Chat GPT tells us:

Using environment.yml for Conda-based builds: RTD supports Conda-based builds if you include an environment.yml file in your project. RTD will use Conda to create the environment specified in the environment.yml, and you can define all dependencies there. However, this environment is managed by RTD during the build process, and you won't be able to access CONDA_PREFIX directly.

Accessing Conda in the RTD Build: While you can define a Conda environment, the RTD build process does not expose environment variables like CONDA_PREFIX for direct access in the documentation. If you need access to environment-specific paths, you would need to use a custom script or configuration that retrieves the required paths or set environment variables within your documentation.

[NoraLoose]

Would it be okay if we set CONDA_PREFIX to a dummy string in RTD? Or would something else break?

[dafyddstephenson]

I assume It's not running anything so I think it would be fine!

[NoraLoose]

Okay, I finally got this working but the solution is not totally satisfying: I fooled C-Star by hard-coding os.environ["CONDA_PREFIX"] into the docs/conf.py:

# cstar will look for os.environ["CONDA_PREFIX"] but this is not available on RTD; let's fill it with dummy
os.environ["CONDA_PREFIX"] = str(root)

The question is whether we can move the things happening in https://github.com/CWorthy-ocean/C-Star/blob/main/cstar/base/environment.py elsewhere, so that these variables are only set if you actually want to make a run (RTD does not want to make a run, just build the API ref). I will open an issue about this, but merge this PR so that we have a working documentation.