Syncing the CABLE documentation for CABLE and JULES

[ccarouge]

JULES requires us to put some documentation for CABLE in the JULES documentation.
The JULES documentation is using .rst format for its files. It's a powerful markup language but it can be tricky to master. You can see a file we have for CABLE as an example.

I don't want to use .rst as I think it's too complicated to master. And anyway we wouldn't have the same markup conventions as JULES and would need to convert the files between the 2 documentations. Markdown is used a lot but RsT is also used a lot, by all (most) sites having their documentation under readthedocs.

I have tried to convert the file with the documentation for the veg. parameters from JULES to Markdown and here is the best I can get. This would require quite some work to get right.

I have then converted this Markdown file back to RsT and the result isn't too bad but I'm guessing it would be worst starting from a straight Markdown file. We will have a problem with maths notations

What do you think @rkutteh and @JhanSrbinovsky ?

Are we going to make too much work for ourselves by using Markdown for CABLE's user guide?
Or would using RsT be quite a bit of work anyway? First, we would have to learn the format and it's not the most friendly and then, we have to modify our RsT files to satisfy JULES customisations. And no inline documentation for Fortran is using RsT, so 2 different formats would be used in the documentation.

[rkutteh]

This is a difficult question to answer at this stage, at least for me. I would need a crystal ball. I had a quick read on the web about the pros and cons of rst and md (e.g., https://www.zverovich.net/2016/06/16/rst-vs-markdown.html#:~:text=According%20to%20John%20Gruber%2C%20the,designed%20for%20writing%20technical%20documentation.) but I find it difficult to give any answer before having tried to use each language for a bit of time. I am happy to use md for now and try on the side the rst equivalent, and I think then I may be able to give a more educated response. So how about if we continue for a little while longer with the present arrangements and revisit the topic say at the next meeting in Dec ?

[ccarouge]

Thanks for the link @rkutteh. It seems to me the biggest advantage of RST is when it comes to write API documentation. But if we are using FORD for the API then it cancels that advantage of RST.

From the post:

In addition to this, Sphinx provides a set of roles and directives for different language constructs, for example, :py:class: for a Python class or :cpp:enum: for a C++ enum. This is very important because it adds semantics to otherwise purely presentational markup:

The :meth:`str.format` method and the :class:`Formatter` class share the same
syntax for format strings (although in the case of :class:`Formatter`,
subclasses can define their own format string syntax).

I don't think RST supports Fortran specifically anyway for the directives etc., so there is no access to API documentation niceties. On the contrary, FORD provides a similar way to refer to various parts of the code by specifying the type (module, subroutine, type etc.)

For the maths, the tools we are using support MathJax so that isn't an issue.

There is the problem of multi-language support but if we need it then we will have to use Doxygen for Fortran automatic documentation anyway.

One issue might be if we want to create a PDF version of the documentation.

I am not saying I have made a decision here, just trying to summarise the points of the author of the post as applied to CABLE here. Feel free to disagree with any of my interpretations.