Documentation

[aekiss]

Just trying to draw together our various discussions on documentation here.

It would be good to have a systematic and unified approach to documentation. I've listed several things that would be nice to have; not clear if all are achievable. In no particular order:

1. versionable - linked to specific commits/tags
2. automatically updateable, e.g. using nmltab, for example as done in access-om3-doc
3. web-searchable
4. useful for documentation paper
5. compatible with Hive (markdown) https://access-hive.org.au/about/contribute/contribute_on_github/
6. easy: low barrier to entry for new contributors - could be crucial to having it kept up to date
7. github integration
8. readily transfer markdown documentation from ACCESS-OM3 wiki https://github.com/COSIMA/access-om3/wiki
9. and more - please add anything else

It seems there are 3 formats we might consider:

• latex - used for ACCESS-OM2 tech report, which was good for item 4 and did automatic formatting, indexing and linking and had automatically-updateable parameter tables using nmltab but did not get a lot of community contribution (perhaps too hard to be involved?) and didn't hit many of the other items.
• rst (reStructuredText) - capable and versatile, used in Sphinx, great for python; also has Fortran mode; used in MOM6 and CICE6 and payu docs; MOM6 also creates rst documentation of Fortran code via Doxygen; can be hosted on readthedocs
• markdown - less capable than rst but easier and familiar to users of github, forum, and slack; used in MkDocs, which is used in Hive - hits items 3, 5, 6, 7, 8 and 2 (nmltab can output to markdown)

There are also tools than can convert between documentation formats, e.g. pandoc.

I think the choice is between rst/Sphinx and markdown/MkDocs. On balance I think markdown might be the best option mainly because of ease of use, but I'm happy to hear from anyone with more experience.

related:
COSIMA/om3-utils#4
COSIMA/access-om3-doc#1
#92
#117

[aekiss]

A related, and probably trickier question is now to structure the documentation files.

We have a code repo and multiple config repos, each of which has several configuration branches, and all of which is subject to updates.

One way to hit item 1. would be to have the entire documentation repeated in each config branch, but with specific details matching that specific branch. This would then be tracked with git, but this would require some automatic way to propagate common documentation changes across all configs in a repo, or all config repos. Perhaps we'd need to break the docs into multiple files so that changes specific to one config branch will only affect one file.

related: #119

[micaeljtoliveira]

Before making any decisions, might also be worth considering how the OM3 documentation will interact with the corresponding ACCESS-Hive documentation, as to avoid duplicating content.

[aekiss]

Re. structure, there are two main options that I can see (1 is my preference):

1. have entire doc repeated (with necessary modifications) in each branch of each config repo
   • config PRs could include doc update commits to the same branch, facilitating keeping docs up to date and unambiguously linking docs to specific config commits.
   • checking out a branch also checks out the complete docs for that specific commit - provides a correct reference for users, including those using older config versions
   • cross-config sync tools (Automate parameter sync across configs #119) would also sync documentation updates for changes that are applied across multiple configs
   • flexible: doc in each branch can be arbitrarily different - doesn't assume any particular hierarchy of config similarity/difference - but cross-config sync could become difficult to automate if doc is too divergent and unstructured - would be good to break doc into multiple files (eg for each subsection) to make auto updating with git cherry-pick more reliable
   • may be awkward to host doc for multiple branches on readthedocs etc?
2. avoid repetition by having common documentation sections stored centrally, and config-specific docs in branches
   • need some automated way to construct docs for each config by drawing it all together
   • makes it easy to update common things in one place, since most of docs will be pretty similar across configs
   • but not naturally tied to commits on individual branches - could be ambiguous as to what commits the doc applies to (and vice versa), and hard to enforce doc updates when configs are updated
   • hierarchy of common vs specific details would need to be carefully thought through to be flexible enough to handle unanticipated future needs, eg new configs
   • how to handle overriding of generic common case by a change in one a specific branch, ie one branch differing from the common case? Would that require moving a copy of the nearly-common case into all the other branches? Then we're back to case 1. but less elegantly. Alternatively we'd have docs with common case but lots of caveats for specific configs which could be confusing to read and maintain.

[aekiss]

At today's TWG @aidanheerdegen suggested using a structured format for documentation sources (e.g. yaml like we do for metadata).

This would be applicable to either option 1 or 2, and would provide structure and facilitate automated extraction of specific parts of the documentation.

Would there be any notation clashes between the structured data notation (say yaml) and markup language (say markdown)? e.g. would complying with yaml format restrict what we can express in markdown?