search

COSIMA / access-om3-doc

Documentation for COSIMA's ACCESS-OM3 global ocean - sea ice - wave model
1 stars 0 forks source link

Use Overleaf? #1

Open dougiesquire opened 11 months ago

dougiesquire commented 11 months ago

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 commented 11 months ago

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

micaeljtoliveira commented 11 months ago

@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 commented 11 months ago

mkdocs or readthedocs is the way to go I think

dougiesquire commented 11 months ago

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 commented 11 months ago

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 commented 11 months ago

Apologies - jumped the gun

aekiss commented 11 months ago

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 commented 11 months ago

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 commented 11 months ago

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 commented 11 months ago

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?