Fix broken sphinx build

[jbusecke]

Summary: This pins a buch of packages to deal with an issue that broke backwards compatibility for sphinx<5 (more info here: readthedocs/readthedocs.org#11140). I also moved all of the dependencies for the doce into doc/environment.yaml to avoid confusion/duplication vs dependencies defined in setup.py.

• Passes pre-commit run --all-files
• User visible changes (including notable bug fixes) are documented in whats-new.rst

[navidcy]

Do you need to add the compat requirement here:

xgcm/setup.py

Line 16 in 2bafd2a

"sphinx",

?

[IamShubhamGupto]

I was able to bump sphinx version by just hardcoding it in the environment.yml in #627 . Since the build seemed fine with v4.5.0, I just stuck to it

[jbusecke]

I was able to bump sphinx version by just hardcoding it in the environment.yml in #627 . Since the build seemed fine with v4.5.0, I just stuck to it

I have done that here. This is so confusing!

[jbusecke]

Do you need to add the compat requirement here:

xgcm/setup.py

Line 16 in 2bafd2a

"sphinx",

?

Trying that rn. Our whole build is very scattered. Ill dig further into this...sorry for this mess everyone.

[jbusecke]

Ok I think I found what is going on:
From here

It seems they just inject another -sphinx to the environment file 🙈.

[jbusecke]

Ok I am getting some releavant gh issues: readthedocs/readthedocs.org#11140 with a suggested workaround here. Going to give that a spin...

[jbusecke]

Ok I gotta stop here. I moved all the docs requirements back to the conda env file (and removed them from the setup.py extras_require) since I was not able to get the build to run without installing pandoc via conda/mamba. At least this now is less confusing to the user who might have thought previously that you can build the docs with pip install ".[docs]" only.

My build locally succeeded (with a lot of warnings and things we should address), but If this passes I will merge and rely on #627 and follow ups to dig further into cleaning the whole process up.

Maybe we should just use jupyter-book to build the docs to github pages...this all seems extremly gnarly still.

[jbusecke]

Thanks to @IamShubhamGupto for some of the work in #627 that we decided to factor out into this "fixing main" PR that can then be followed by a more thorough clean up of the docs.

[jbusecke]

Nice this worked. Ill merge this now..