[MITgcm-devel] migration to github and readthedocs

[Martin Losch]

Hi Ryan,

> On 21. Jul 2017, at 21:00, Ryan Abernathey <ryan.abernathey at gmail.com> wrote:
> 
> I just wanted to chime in with a counterpoint. For me, the process of contributing to the docs has always seemed intimidating. I couldn't figure out how to build them locally, and I was reluctant to commit changes "blind" without previewing them first. ReST, Sphinx, and readthedocs is a widely used and familiar format and platform for many people, including myself. So in the future, I think I will be more likely to contribute to the docs if we can manage to migrate them.
I had never heard about ReST before last week, and I don’t know anyone how does, but then again, I may not know enough people under 35 (o:
I agree: it builds much faster, it looks much better, didn’t have any problems installing and building (not a single glitch, but I had a working python environment, which probably puts me ahead of few people).
Latex is much more powerful and defintely has a larger community. It feels strange to let go off all that support.
I usually have a working latex (and was assuming that nearly everyone in the natural sciences/maths community does) so I am surprised that building the docs can be a problem. I admit: I never build the html-pages locally, just the pdf (via “make pdf”) and assumed that latex2html will work if the pdf-build is successful. (I never build the entire latex-based docs, just the sections that I edited). I never found it intimidating.
> 
> But at the same time, I recognize that the friction and frustration Martin experienced is a major downside. Hopefully a balance can be found between evolving to a more modern platform and not alienating the most productive and enthusiastic MITgcm contributors! Ed had some great suggestions on how to achieve that.

I think that the new looks of the (test-)manual are great and I think that I can probably get used to ReST. In the end it not very hard to understand. I only find the process of compiling and having to view the result with an html-browser tedious, because my browsers do not reload the page at the place where I left off. Part of my frustration comes from the fact that I am trying to learn two things at a time (actually three: git, the new workflow, and ReST, with the mentioned unhelpful viewing options).
In the end, since the ReST-sources are somewhat simpler than latex, it will probably make it easier for most people to contribute. I am sure that we can find or create tools for fixing the remaining issues (e.g., some parser that replaces macros with something recognizable that will not compile, so it’s not missed, or something that replaces \citep{} and \citet{} with :cite:`` or similar, I am sure you can train “sed” to do that (o:).

Martin