Generate documentation with Windows

[Zeitsperre]

Pull Request Checklist:

• This PR addresses an already opened issue (for bug fixes / features)
  • This PR fixes #xyz
• (If applicable) Documentation has been added / updated (for bug fixes / features).
• (If applicable) Tests have been added.
• CHANGELOG.rst has been updated (with summary of main changes).
  • Link to issue (:issue:number) and pull request (:pull:number) has been added.

What kind of change does this PR introduce?

• Adds a batch file for generating translations and documentation

Does this PR introduce a breaking change?

No.

Other information:

The final accepted PR should not include a workflow. This tool should be available for local execution by Windows users.

My assumptions for Windows users are:

• nmake is not available (no make utilities)
• MinGW and gitbash are not available (no BASH shell)
• PowerShell is available (installed by default on Windows 7+ systems)

[Zeitsperre]

I can't seem to install a working environment for xhydro on Windows due to a bug in ESMF v8.4.2:

Configuration error:
There is a programmable error in your configuration file:
Traceback (most recent call last):
  File "C:\Users\runneradmin\micromamba\envs\xhydro-dev\lib\site-packages\sphinx\config.py", line 529, in eval_config_file
    exec(code, namespace)  # NoQA: S102
  File "D:\a\xhydro\xhydro\docs\conf.py", line 32, in <module>
    import xhydro  # noqa: E402
  File "D:\a\xhydro\xhydro\src\xhydro\__init__.py", line 21, in <module>
    from . import cc, gis, indicators, modelling, utils
  File "D:\a\xhydro\xhydro\src\xhydro\cc.py", line 9, in <module>
    from xscen import climatological_op, compute_deltas, ensemble_stats, produce_horizon
  File "C:\Users\runneradmin\micromamba\envs\xhydro-dev\lib\site-packages\xscen\__init__.py", line 6, in <module>
    from . import (
  File "C:\Users\runneradmin\micromamba\envs\xhydro-dev\lib\site-packages\xscen\aggregate.py", line 23, in <module>
    import xesmf as xe
  File "C:\Users\runneradmin\micromamba\envs\xhydro-dev\lib\site-packages\xesmf\__init__.py", line 3, in <module>
    from . import data, util
  File "C:\Users\runneradmin\micromamba\envs\xhydro-dev\lib\site-packages\xesmf\util.py", line 8, in <module>
    import esmpy as ESMF
  File "C:\Users\runneradmin\micromamba\envs\xhydro-dev\lib\site-packages\esmpy\__init__.py", line 106, in <module>
    __author__ = msg["Author"]
  File "C:\Users\runneradmin\micromamba\envs\xhydro-dev\lib\site-packages\importlib_metadata\_adapters.py", line 54, in __getitem__
    raise KeyError(item)
KeyError: 'Author'

The good news is that it seems as though there's recent work to finally port the latest ESMF (v8.6) to Windows on Anaconda: conda-forge/esmf-feedstock#119.

Unless I can get access to a Windows machine with an environment configuration that works, this PR is blocked for now.

[Zeitsperre]

The issue was importlib-metadata complaining about the metadata in xesmf. The make-docs.bat script should work on Windows machines. Minor tweaks might be needed.

@RondeauG and/or @sebastienlanglois, can you try running this script in your respective Windows environments SVP ?

[RondeauG]

Is there a danger to pin this for everyone?

Also, I don't know exactly why this is required for it to work on GitHub, but my local setup works with importlib-metadata 8.4.0, esmpy 8.4.2, xesmf 0.8.7 without any issue...

[Zeitsperre]

I grabbed this fix from here: CLIMADA-project/climada_petals#132.

I don't think it is dangerous, but from my understanding, the fact that the metadata is corrupted in esmpy/esmf, we need to have an older version here, otherwise this raises ValueErrors on import.