Use Overleaf?

[dougiesquire]

Overleaf is an online Latex editor that facilitates online collaborative editing of latex documents. I've been using it for a while and it's excellent.

Overleaf also has GitHub integration/synchronisation. It's a paid feature, but it could work pretty effectively here. I could investigate the possibility of ACCESS-NRI paying for a license?

[dougiesquire]

Just noticed all the git-hook stuff, so maybe this isn't a good idea unless they work with the Github integration...

[micaeljtoliveira]

@dougiesquire The idea was to use something that we can easily deploy to github pages, like mkdocs or readthedocs.

Edit: unless @aekiss as a different idea in mind for this repository. Last week we discussed about moving the content of the wiki to github pages at some point in the future, but maybe that would a different repository?

[navidcy]

mkdocs or readthedocs is the way to go I think

[dougiesquire]

deploy to github pages, like mkdocs or readthedocs

Then would it be easier to write the docs in md or rst, rather than tex?

[aekiss]

Hi sorry for the confusion, this repo is mostly me trying out some ideas - I probably should have put it in my own space rather than COSIMA.

[dougiesquire]

Apologies - jumped the gun

[aekiss]

No worries, and yes Overleaf is awesome. I explored using it for the OM2 tech report and have a flag to disable gitinfo git-hooks for overleaf.

[aekiss]

I'm a bit torn on the best format to use.

Latex made it easy to generate tables of parameters which were linked to from the main text in the ACCESS-OM2 tech report, e.g. \mom{barotropic_split} formats this correctly, adds it to the index, and links it to the table of parameters in the appendix (which is in turn linked to a search of the codebase on github). The parameter tables in the appendix are all automatically generated by https://github.com/aekiss/nmltab and readily updated. I have a feeling this would be more cumbersome to do in markdown or rst but maybe I'm wrong about that. I think this would be an important feature to have, to make it easier to keep docs in sync with configs. nmltab can output tables in markdown but it would take some work to make it as nice as the latex output.

The OM2 tech report also served as a draft of the model description paper, so it was convenient that it was also in Latex.

OTOH it is a lot nicer and more searchable to have docs on the web in html...

[aekiss]

Is stuff like this possible in anything but latex? Particularly the automatic generation of hyperlinks and targets based on parameter names (and handling parameters with underscores).

https://github.com/COSIMA/access-om3-doc/blob/main/access-om3-doc.tex#L118-L153

https://github.com/COSIMA/access-om3-doc/blob/main/access-om3-doc.tex#L291-L292

[dougiesquire]

It's possible to convert Latex directly to HTML. I've no idea how well these tools would deal with complex tables, hyperlinks etc, but it might provide an easy way to have both?