Documentation for MONC

[leifdenby]

I'd like to get a discussion started about how we want to make documentation for MONC available. My aim would be the documentation that satisfies the following:

1. Is part of the source-code - whenever you get a copy of MONC you also have a copy of the documentation which matches that copy of MONC
2. Is available for all tagged version as a website so that it easily accessible and searchable
3. Is tied to the source-code so that each function/method/module in MONC is discoverable through this online documentation
4. Has for each addition/change to MONC an accompanying addition/change to the documentation. So that pull-requests will only be merged if there is documentation for the new feature/change.
5. Is automatically generated and put online for every new tagged version of MONC

What do people think about this?

To get the ball rolling on this I have set up Doxygen-based documentation which parses the source-code of MONC and generates a website where one can search through the source code. That is work in progress (see #30). The way this is currently set up any time the master branch is changed on our fork the documentation is automatically regenerated and made available on https://leeds-monc.github.io/monc/ (it needs a bit more work to compile only for tagged version, and for all tagged versions).

I would like to build on this Doxygen-based documentation by adding more markdown-formatted files to doc/ in the repository (here's what I've got so far: https://github.com/Leeds-MONC/monc/tree/doxygen-action/doc). This would cover each of the model components and I was planning we'd take content (with attribution) from the MONC documentation LaTeX document that Adrian and Todd have been working on: https://www.overleaf.com/project/5e467337742dd800019e2448. What do people think about this idea? How should we organise the doc/ folder? A file for each component microphysics.md, radiation.md etc? Sub-directories with related functionality?

[ralphburton]

Leif, this sounds a really good idea. Thumbs up from me.
I think a useful way of looking at it is to imagine being completely new to it (like me, more or less). Then I would like to know from the documentation:

• How do I compile the code on my machine (so - compilation instruction for different machines/architectures). This is the main thing I think - once you have got a working version running you can learn, but without that, it's a largely academic exercise
• What do all the various configuration parameters actually mean?
• What is considered an appropriate/good combination of parameters? Are there any combinations that are inappropriate, common pitfalls, etc? I guess the testcases cover the former. Some more documentation on the latter may avoid the problems we have had with IO etc,
• Related to the above, are there any specific machine-dependent interpretation of the parameters? (e.g. moncs_per_io etc)
• I think WRF documentation is a really good example of how it can be done. There is a "User's Manual" that details all the things you need to get WRF working, and a "Technical Manual" that describes the equation set, parametrisations, etc. Many people don't bother with the Technical Manual but it is there if you need it.
  Just a few thoughts but I think some proper documentation is a great idea!
  Cheers
  Ralph

[sjboeing]

Hi @leifdenby

I don't have a lot of experience actively using doxygen (I mostly look at model documentation and comments in the code), but it sounds like a good idea to use the format whenever we can. I think leaving other documentation in a tex format may be OK: a main thing to avoid is having (possibly incompatible) documentation in multiple places (tex and md files).