Moving documentation into gh-pages

[daniellivingston]

Would it make more sense over the long term to move all documentation from master into gh-pages?

Benefits: less documentation commits in master tree, CI isn't triggered on each doc change

[banesullivan]

Would it make more sense over the long term to move all documentation from master into gh-pages?

Yes, absolutely.

I might be able to help you all deploy this...

[daniellivingston]

Good to hear from you again @banesullivan !

We use Jekyll (via GitHub Pages) to deploy a static site on lanl.github.io/LaGriT through Markdown files (and some html/css assets) in docs/.

The way I see it, there are pros and cons to moving docs/ into gh-pages:

• Pro: cleans up master. The commit tree on master isn't clogged up by minor documentation fixes.
• Pro: TravisCI wouldn't be triggered on each documentation update.
• Con: end-users, who may be viewing documentation locally, would have to explicitly checkout gh-pages to view documentation and checkout master to compile/test/develop/etc. Not too much of a fan of that.

What's the best practice for a situation like this?

[banesullivan]

Normally, gh-pages is used to deploy documentation (having some source like markdown or RST and building a site). Considering you all are using Jekyll with markdown for the home site and sphinx-doc for building the PyLaGriT docs, it might be worth redoing the documentation so that it is all in one cohesive framework. At the moment, I would suggest sphinx-doc for the whole thing.

I will have to think about this a bit more as the docs for LaGriT are a bit fragmented at the moment and there is a lot of material to include.

Perhaps this should come after #196. In that PR, the examples need to be executed to ensure they and the Python API are all in working order. But after that, it might be a good idea to migrate those examples directly into the documentation and use sphinx gallery to test and include those examples.

[daniellivingston]

I definitely agree that PyLaGriT Sphinx documentation should be built as either part of CI or as a Travis cron job.

I don't think we'll migrate the main documentation from Jekyll to Sphinx though, for the following reasons:

1. Documentation are all Markdown files. Sphinx only accepts reStructured Text, as far as I'm aware
2. Markdown is (ostensibly?) a superset of HTML, and we definitely rely on inline HTML in certain places when the MD spec isn't sufficient
3. Moving from Jekyll to another static site generator (like Sphinx, Gatsby, Hugo, mkDocs, etc.) is a moderate amount of work for, probably, a minimal amount of gain. That is to say, all we really need are Markdown files compiled as a static site. Jekyll, for all its troubles, does this fine (and transparently - no build artifacts) and it's not clear what another static site would offer on top of this.

Just my two cents. :) I've experimented with just about every major static site generation framework and Jekyll is one of my least favorites, but the native integration with GitHub Pages is unbeatable for our particular use-case IMHO.