Handling of documentation

s-poll commented 1 month ago

Hi all,

I just saw that the new documentation in the eCLM repository is ready to be released eCLM PR #38. Having a documentation (nicely looking) was long overdue. However, I would also favor to have in-repo documentation, as this is the easiest way to ensure synchronization between documentation and source code. This is now the case for the eCLM part, but also the part of the case creation, which belongs to the eCLM_static_file_workflow is part of it.

I would be in favor to move the section case creation to this repository and just reference to the workflow-documentation in the elm-documentation.

What are your thoughts on that? Explicitly mentioning @odombro, @kvrigor and @AGonzalezNicolas as you are - to my knowledge - involved in the creation of the documentation.

AGonzalezNicolas commented 1 month ago

I agree that the case creation section should go into the repository eclm_static_file_workflow.

kvrigor commented 1 month ago

I'm also in favor of built-in docs as it makes a code repository self-contained. However from the user's POV, I think it's ideal to access all eCLM-related information from a single place, which is the eCLM doc website itself. A workaround is to link the case creation docs to this repo, but this will have the following consequences:

The doc CI build workflow will become more complicated since the content would have to be fetched from multiple repos.
Editing docs will be more complicated as pull requests would have to be raised on separate repos.
A separate doc website could be set up for this repo, but this would fragment the eCLM docs which IMO is an unnecessary complexity.

I believe we should avoid additional maintenance burden as much as possible. Also, we could encourage more user contributions if the editing workflow is much easier.

How should we resolve the dilemma of having self-contained docs vs. a centralized one? One solution could be to git submodule this repo under eCLM. This minimizes maintenance overhead but doesn't address the complicated editing workflow, which may be an acceptable compromise. Any other ideas?

odombro commented 1 month ago

Would it be an option to merge these two repos into one? I have mostly left out the ICON-specific part of the case creation workflow for the eCLM documentation but it could be added again to not miss this part for ICON users.

kvrigor commented 1 month ago

Would it be an option to merge these two repos into one?

I'm OK with this. Since domain and surface files must be compatible with eCLM inputs, I think it's only natural to embed tools that generate eCLM inputs within the eCLM repo itself. Also this allows to improve the existing case creation scripts in a way that takes advantage of eCLM model codes (e.g. directly calling Fortran subroutines from Python).

DCaviedesV commented 1 month ago

I have a different opinion here. In my view the model's code is one thing. Case creating, workflow management, and anything else, are different projects and thus different repositories. They are certainly related and intertwined. However, keeping everything together, although it provides a one-stop-shop, also blurs the differences between these aspects for the user (where does the model start/end, where do the workflows start/end?), and for the maintainers (who is responsible for which part, if it is all in the same bag?). In the end you don't really need the eCLM_static_file_workflow to operate eCLM... it is convenient, but it is an additional tool, not a core part of the solver. The analogy for this is the TSMP code and the TSMP workflow manager, clearly not the same thing, but all works together.

jjokella commented 1 month ago

My opinions on this issue. I am

for separating case creation and source code
for repository-related documentation inside the corresponding repository

In my opinion, what is most important (and sometimes lacking), is linking of all the different resources to each other (very important for the user experience also).

Suggestion: Does this issue have to block the documentation PR on eCLM https://github.com/HPSCTerrSys/eCLM/pull/38 ? For the sake of simplicity, I propose merging https://github.com/HPSCTerrSys/eCLM/pull/38 and applying necessary re-arrangement of the doc after this discussion has reached a conclusion.

AGonzalezNicolas commented 1 month ago

I am with Johannes and Daniel: separate case creation and source code.

kvrigor commented 1 month ago

I'd also vote to close the https://github.com/HPSCTerrSys/eCLM/pull/38 and do the next round of improvements on a new pull request.

HPSCTerrSys / eCLM_static_file_workflow

Handling of documentation #2