Separate ESMValTool and ESMValCore documentation #3914

flicj191 · 2025-02-13T04:24:54Z

Description

Draft PR to build documentation separately

Closes Documentation separation ESMValTool and ESMValCore #3860
Link to documentation: https://esmvaltool--3914.org.readthedocs.build/en/3914/

Parallel esmvalcore pr:
ESMValGroup/ESMValCore#2732

Before you get started

☝ Create an issue to discuss what you are going to do

Checklist

It is the responsibility of the author to make sure the pull request is ready to review. The icons indicate whether the item will be subject to the 🛠 Technical or 🧪 Scientific review.

🛠 This pull request has a descriptive title
🛠 Code is written according to the code quality guidelines
🛠 Documentation is available
🛠 Tests run successfully
🛠 The list of authors is up to date
🛠 Any changed dependencies have been added or removed correctly
🛠 All checks below this pull request were successful

To help with the number of pull requests:

🙏 We kindly ask you to review two other open pull requests in this repository

valeriupredoi · 2025-02-13T12:57:35Z

wonderful, many thanks for taking on this @flicj191 🍺

flicj191 · 2025-04-24T05:22:43Z

https://esmvaltool--3914.org.readthedocs.build/en/3914/index.html

top navigation is simplified
document navigation on the side splits the parts
consider maintaining current domains? and keep subproject

flicj191 · 2025-05-23T03:51:12Z

Parallel esmvalcore pr:
ESMValGroup/ESMValCore#2732

ehogan

Thanks @flicj191 🎉

I added some thoughts. I hope they are useful! 😊

doc/sphinx/source/index.rst

doc/sphinx/source/_templates/cross_proj_navbar.html

ehogan · 2025-05-30T12:07:12Z

doc/sphinx/source/index.rst

+How to contribute
+-----------------
+Refer to ESMValTool :ref:`contributing to the community<community>` for a guide on contributing recipes and diagnostics.

-For more detailed information, the documentation is available below.
+Refer to ESMValCore :ref:`Contributing <contributing>`  for information on contributing code.

-Get in touch! Contact information is available :ref:`here <Support-and-Contact>`.
+Get in touch!
+-------------
+Contact information is available :ref:`here <Support-and-Contact>`.


It might be useful to have this information on every page. Could it be added to the footer, or the secondary sidebar (under the "Show Source" link)?

Good idea!
So you mean each of the 3 links? (ESMValTool contributing, ESMValCore contributing, Support and contact)

Maybe just "ESMValTool contributing", then "support and contact"? The ESMValCore pages can have the equivalent "ESMValCore contributing"?

(I have code that can create the following in the secondary sidebar, if you'd like me to share) 😊

This change would also make the main page less busy 😊

Thanks @ehogan can you share the code please? I think there could also be a version thing going on as it doesn't look quite the same as what the theme documentation is showing

I opened a new issue for this (#4215) to allow this PR to be merged 😊

doc/sphinx/source/_templates/cross_proj_navbar.html

doc/sphinx/source/_templates/sidebar_nav_lv1.html

doc/sphinx/source/index.rst

ehogan · 2025-05-30T12:31:19Z

doc/sphinx/source/index.rst

+.. container::
+   :name: figarch
+
+   .. figure:: figures/ESMValSchemaDiagram.png
+      :alt: Brief topics for tool and core.
+      :figclass: align-center


I like the diagram; would it be worth also adding specific links to the topics mentioned?

I was thinking its more a condensed diagram to assist in understanding with the broader topics but these topics might need to be reviewed and refined, I'm not sure there would be appropriate specific links to them all

Having a nice diagram like this one (plus the two describing sentences) on the landing page makes the relation of the packages very clear. Well done.
Providing links to each topic here would also require revision whenever structure in the documentation changes. I'd keep the image as conceptional and condensed as possible and make the sidebar as structured and self explanatory as possible. As the sidebar only shows the structure of the ESMValTool part, do you think we should link to the ESMValCore documentation again. In the last sentence here and/or the description of the ESMValCore package above?

@bouweandela for the diagram, fair point with links as well but it was a rough diagram and I wasn't thinking of specific pages but just to help with understanding. If topics get out of date it would still need to be updated even if links are still correct?

I still think it would be nicer to generate it dynamically from the documentation pages, but if that's technically too challenging, it's fine to leave it as is.

flicj191 · 2025-06-18T01:18:25Z

@ehogan Thanks very much for your comments! They were useful, sorry it's been a delay to get back to this.

@ehogan

Co-authered-by: @ehogan

…c_split

flicj191 · 2025-07-16T02:48:12Z

If we are sure, that the esmvalcore documentation will still be deployed as part of the esmvaltool documentation I'm happy to approve the PR. Otherwise I'd like to run some link checkers again, since I suspect there could be some hardcoded references in the documentation.

Thanks very much @lukruh! Your comments were helpful! This I'm not too sure with the advantages/disadvantages and may need to be discussed in a meeting/workshop

lukruh

Thanks for the additional changes. The documentation appears a lot cleaner and better structured. I'd like to see this merged before the next workshop.

…c_split

flicj191 · 2025-07-22T04:40:38Z

Thanks for your help @lukruh!
Any other thoughts? @ehogan @malininae @bouweandela @valeriupredoi @rbeucher

ehogan

This is really great, thank you for all your hard work on this @flicj191! 🎉

A few additional suggestions from me 😊

doc/sphinx/source/conf.py

doc/sphinx/source/_templates/cross_proj_navbar.html

doc/sphinx/source/index.rst

doc/sphinx/source/_templates/cross_proj_navbar.html

doc/sphinx/source/figures/ESMValSchemaDiagram.png

Co-authored-by: Emma Hogan <[email protected]>

ehogan

Many thanks for your hard work on this @flicj191! 🎉

The outstanding comments I had have been captured in a new issue (#4215), so I am approving this PR 😊

…c_split

flicj191 added 3 commits February 11, 2025 09:45

test sidebar change

091c3d2

generate gallery

f669fe1

remove gallery to build

f7e6528

flicj191 added 2 commits February 18, 2025 14:31

add back gallery and custom header

e24b0ca

sidebar list in index

8e4a72c

flicj191 and others added 2 commits May 14, 2025 13:44

Merge branch 'main' into doc_split

05907a8

search text

a7253e6

flicj191 mentioned this pull request May 15, 2025

Documentation layout to highlight 2 packages ESMValGroup/ESMValCore#2732

Merged

10 tasks

flicj191 and others added 3 commits May 23, 2025 14:05

landing page update add image

f61fb09

remove contributing link

87f1fff

Merge branch 'main' into doc_split

94792de

flicj191 marked this pull request as ready for review May 23, 2025 04:31

flicj191 requested review from ehogan and malininae May 23, 2025 04:31

ehogan reviewed May 30, 2025

View reviewed changes

lukruh mentioned this pull request Jun 17, 2025

Update figure selection and layout of the gallery #4060

Merged

flicj191 requested review from lukruh June 18, 2025 00:43

flicj191 and others added 6 commits June 18, 2025 11:31

Update index toctree to hide and top bar

7c91792

Co-authered-by: @ehogan

Merge branch 'doc_split' of github.com:ESMValGroup/ESMValTool into do…

7af464b

…c_split

Merge branch 'main' into doc_split

6807660

error in toc

3e3ee1a

Merge branch 'doc_split' of github.com:ESMValGroup/ESMValTool into do…

6d1e6a9

…c_split

gallery top bar, format gensidebar

18fdb3b

flicj191 added documentation looking for technical reviewer labels Jun 18, 2025

fix toc

2d83bf0

flicj191 added 2 commits July 16, 2025 12:48

remove gensidebar

58eb780

fix whitespace

7dedf22

lukruh approved these changes Jul 16, 2025

View reviewed changes

Merge branch 'main' into doc_split

a05b019

lukruh added approved by technical reviewer and removed looking for technical reviewer labels Jul 16, 2025

flicj191 added 2 commits July 17, 2025 11:22

fix dark transparent background image

b2911f8

Merge branch 'doc_split' of github.com:ESMValGroup/ESMValTool into do…

4b2ce30

…c_split

flicj191 removed the request for review from malininae July 22, 2025 04:34

ehogan requested changes Jul 23, 2025

View reviewed changes

doc/sphinx/source/conf.py Outdated Show resolved Hide resolved

doc/sphinx/source/_templates/cross_proj_navbar.html Show resolved Hide resolved

doc/sphinx/source/index.rst Outdated Show resolved Hide resolved

bouweandela reviewed Jul 23, 2025

View reviewed changes

doc/sphinx/source/_templates/cross_proj_navbar.html Outdated Show resolved Hide resolved

bouweandela reviewed Jul 23, 2025

View reviewed changes

doc/sphinx/source/figures/ESMValSchemaDiagram.png Show resolved Hide resolved

flicj191 and others added 4 commits August 1, 2025 11:43

Apply suggestions from code review

335b0a1

Co-authored-by: Emma Hogan <[email protected]>

Merge branch 'main' into doc_split

1fc0ef6

header icons test

8e995ab

Merge branch 'main' into doc_split

376b897

flicj191 changed the title ~~Separate ESMValTool and ESMValCore documentation - restructure header~~ Separate ESMValTool and ESMValCore documentation Sep 4, 2025

flicj191 requested review from bouweandela and ehogan September 4, 2025 22:59

ehogan mentioned this pull request Oct 8, 2025

Minimise content on main documentation page #4215

Open

ehogan approved these changes Oct 8, 2025

View reviewed changes

lukruh and others added 4 commits October 24, 2025 13:42

Merge branch 'main' into doc_split

6b492fa

update header match core docs

92d5c05

Merge branch 'doc_split' of github.com:ESMValGroup/ESMValTool into do…

2a075b3

…c_split

header external links

06af11f

bettina-gier merged commit 5294af4 into main Oct 27, 2025
8 checks passed

bettina-gier deleted the doc_split branch October 27, 2025 09:37

Separate ESMValTool and ESMValCore documentation #3914

Separate ESMValTool and ESMValCore documentation #3914

Conversation

flicj191 commented Feb 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Before you get started

Checklist

Uh oh!

valeriupredoi commented Feb 13, 2025

Uh oh!

flicj191 commented Apr 24, 2025

Uh oh!

flicj191 commented May 23, 2025

Uh oh!

ehogan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

flicj191 commented Jun 18, 2025

Uh oh!

flicj191 commented Jul 16, 2025

Uh oh!

lukruh left a comment

Choose a reason for hiding this comment

Uh oh!

flicj191 commented Jul 22, 2025

Uh oh!

ehogan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ehogan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

flicj191 commented Feb 13, 2025 •

edited

Loading