Show ESMValTool and ESMValCore documentation on a single readthedocs site

[bjoernbroetz]

This PR addresses the issue ESMValGroup/ESMValTool#1155 and is the counterpart to ESMValGroup/ESMValTool#1157.

There is a new utility module introduced in esmvaltool.utils.doc.gensidebar that creates a common sidebar for esmvaltool and esmvaltool-core documentation or any future part of the esmvaltool. If one needs to change the content of the sidebar, it needs to be done in this place.

The configuration file for sphinx was adapted (here and in the other repo) to make use of the utility module.

Also closes #114

[bjoernbroetz]

The accompanying PR at esmvaltool repo is ESMValGroup/ESMValTool#1157

[bouweandela]

Nice job! Would it be possible to move the gensidebar script to the doc directory? That way we keep all documentation stuff together. I would also like to move the documentation to just doc instead of doc/sphinx/source, but maybe that's something for a different pull request.

[bjoernbroetz]

Would it be possible to move the gensidebar script to the doc directory? That way we keep all documentation stuff together.

I tried that first but the now independent ESMValTool repository needs access to this script (when coding in development mode as well as when coding with a preinstalled core part). The original approach of the inventors of this was to copy this script to all subprojects and keep them manually synchronized. I wanted to have it just in one place and to make it part of the esmvalcore-module appeared to me as straightforward.

[mattiarighi]

Can we merge?

[bouweandela]

We need to test that it works first. I've enabled the docu_join branch on readthedocs for both the esmvalcore and esmvaltool repositories. @bjoernbroetz Can you try to get that working? At the moment the build fails. Also, I think as part of these pull requests we need to divide the documentation between the esmvalcore and esmvaltool repositories, because at the moment they both contain the same files, with the ones in esmvalcore being slightly outdated. If possible I would also prefer to keep the documentation for esmvalcore directly in the doc directory instead of in doc/sphinx/source.

[bjoernbroetz]

@bouweandela Thanks for enabling the branches at RTD. The esmvaltool part will need the module esmvalcore available with the enhancements that are in the branch ESMValCore/docu_join at build-time of the docs.
The ESMValTool-core part documentation, however, should build independently. Could you point me to the error messages reported by RTD?

We should first merge the core part.

[bouweandela]

The esmvalcore build information is available here: https://readthedocs.org/projects/esmvalcore/builds/

[bjoernbroetz]

ModuleNotFoundError: No module named 'esmvalcore'

I see. Both documentations (core and diag parts) need the esmvalcore module installed with the enhancements of docu_join.

There is a hint given in the RTD-FAQs:

If you see ImportError messages for custom Python modules, you should enable the virtualenv feature in the Admin page of your project, which will install your project into a virtualenv, and allow you to specify a requirements.txt file for your project.

Sorry, this happens to be a "chicken and the egg" problem. You can only test after you merge, but you will only merge after you test ...

Do we have any idea?

[bjoernbroetz]

So with the requirements.txt we can install from github pointing at a branch:
git+git://github.com/ESMValGroup/ESMValCore@docu_join

Shall we proceed on this way? If yes, I will create such a file in this branch and @bouweandela would need to enable virtualenv at RTD.

[bouweandela]

I fixed some dependency issues and a mistake I made in the rootpath, the documentation now builds successfully for esmvalcore.

[bouweandela]

I've added the gensidebar script to the other pull request as a workaround for testing, it should be removed once we are close to something that works.

[JaroCamphuijsen]

@axel-lauer @schlunma
Could you maybe review the documentation for this pull request? Please review the structure and not the actual content.
The documentation built from this branch (and pull request) can be found here:
https://esmvaltool.readthedocs.io/projects/ESMValCore/en/docu_join/