Plan for the CABLE documentation

Land Surface CABLE
1

We need to reorganise and update the CABLE documentation. We need to discuss what is the best way to do so.

Here are a few thoughts:

  • we need CABLE developers and users to be engaged with the process so that the documentation is pertinent to all and stays updated.
  • the documentation should be easily accessed
  • updating the documentation should become a part of developing the code.
  • the documentation will take some time to finish. We need to prioritise what parts to get ready first while opening to any contributions.
  • we need to decide how much documentation we want within the code itself, knowing we can use automatic documentation software to publish this information to a website.

We also need to decide how to document diverged branches while they haven’t merged with the main version of CABLE. Usually, they have diverged enough that these branches need their own User guide and API documentation. Would it be easier to handle that in a separate repository and documentation site specific to that branch?

If we follow this route, I would also argue, once CABLE is moved to a Git management, the source code for these branches would be easier to manage in separate repositories as well. It wouldn’t prevent merging the code bases. It might actually be easier to create separate Git repositories for these branches anyway.

2

In the last 2 days, we had a CABLE docathon with a few CABLE experts to rejuvenate the CABLE documentation.

A new platform has been chosen (more information) with the source of the documentation hosted in a GitHub repository that will eventually host the CABLE source code as well.

The docathon was successful and has shown a lot of motivation in updating the documentation. But this is a big task and it requires some time investment from all CABLE developers and users. The goals of the docathon were:

  • familiarise everyone with the chosen tools and get feedback on how best to use them
  • focus on the User Guide and the scientific documentation first.

Outcomes

At the docathon, we discussed how best to keep everyone engaged with the process. We have decided so far:

  • develop a timeline for the documentation to increase visibility of shared expectations. First priorities are a User Guide, scientific documentation and a high-level flowchart of CABLE.

  • nominate Code Owners for different parts of the code that are responsible for overseeing progress in the documentation:

    • Gab: driver, I/O and maybe soil
    • Mengyuan: hydrology (GW)
    • Juergen: POP
    • Ian: roughness and canopy
    • Yingping: CASA-CNP and landuse
    • Jhan, Claire: Radiation and albedo

  • Create GitHub issues for each block of work so people can easily find something to work on

  • develop guides and guidelines to help people work independently: GitHub workflow cheatsheet, Markdown cheatsheet, guidelines on what to include in the scientific documentation.

  • hold a second docathon on 13-14th December at UNSW

Open questions

Resolving bug fixes in the code

While documenting various sections of the code, several improvements or bug fixes have been identified. It has been decided to simply put Warnings in the documentation about the potential issues and not to fix these directly. It is the preferred approach generally as it is very easy to loose the focus on the documentation and focus on the code itself instead. However, it is left to each writer to decide whether it is worth documenting the code as is or instead putting the effort into fixing and testing it first.

Format and location of the scientific documentation

The format and location of the scientific documentation are not yet fully decided. The preference would be for the full scientific documentation to be included in the source code to be picked up by the automatic documentation tool. This provides the easiest way for developers to be aware of the documentation and update it. The downside is the level of commenting this would add to the source code. In particular, the UM coding standards point to keeping the amount of commenting reasonable so we need to clarify with the UKMO if this approach would be acceptable. We have discussed other possibilities such as:

  • use “include” files for the inline documentation. This means the scientific documentation would live in separate Markdown files but would appear within the inline documentation. The source code would simply need a one-line comment to include the Markdown file. This solves the problem of the length of the comments in the code but removes direct access to the documentation. Although it keeps the scientific documentation layout identical to the code layout which simplifies finding the part of the documentation to update when developing the code.
  • use separate standalone documentation. It is very similar to the idea of “include” files but it does not force the scientific documentation to closely follow the code organisation.

Not enough Code Owners

So far we have identified no more than 1 code owner per part which is not enough over the longer term. We also have parts of the code without Code Owners: BLAZE, SLI, canopy and soil to some extent.

3

Would it be possible to pre-process the code and strip out comments for submission to the MetOffice? They run subversion anyway right? So you’re going to effectively just check in changes “en masse” and do the actual version control in GitHub?

4

Pre-processing of the code is possible but it could be difficult. FORD supports documentation line by line with a special comment sign at each line, that’s easy. But it also supports blocks of comments with a special comment sign at the start and normal comments afterwards. That’s not the end of the world but it is getting more to build in the pre-processing.

And finally, we wouldn’t want to strip out all comments. The UM coding standards ask for purpose, variable descriptions and references. It leaves some leeway for the developer to give more or less details (but not too much) as needed. So finding a way to organise the comments in the code such that we can automatically remove the surplus might be tricky.

5

Hi,

This looks great! Glad that you settled of FORD. I felt the need for a CABLE flowchart quite a while ago and so I used FORD to make one.
Browse Loughran, Tammas (O&A, Aspendale) / CABLE_autodocs - Bitbucket .
Unitll a better official program flowchart is available, my flowchart is in doc/program/cable_offline_driver.html there in case anyone needs it. (I see the same is already here ). FORD doesn’t allow you to zoom all the way out. I had to manually edit the page in the browser to get the full image of the call and use diagrams (see here).

Cheers,
Tam