Improve documentation and example code

[hadfieldnz]

No description provided.

[hadfieldnz]

I would like to improve PyROMS' documentation and example code (and code for automated testing, but that's another story). It is sensible, I think, to store the documentation files where they can be served by GitHub Pages. My idea is that I will write the documentation and revise the example code at the same time as I learn to use PyROMS.

According to the GitHub Pages instructions the pages for a repository can be stored in one of 3 locations:

• in the master branch
• in the docs folder of the master branch
• in a branch called gh-pages

The first two are problematic for PyROMS because the code I want to document is in the python3 branch. So I have chosen the third option.

In my PyROMS fork, hadfieldnz/pyroms, I have created a gh-pages branch rooted at the initial commit and added an index file that can now be seen at https://hadfieldnz.github.io/pyroms/. I intend to develop this as time permits.

Some time in the future the gh-pages branch could be pulled into ESMG/pyroms and served from there. Or not.

As far as populating the new site is concerned I would appreciate any advice. For examples, I have been looking at the xarray and eofs sites. Both are served on GitHub Pages, though this fact is obscured for xarray because it has a custom domain. Both are built largely in RST format. But perhaps the example code would be better stored in Jupyter notebooks.

[kshedstrom]

If it would help, we can rename the master branch to python2 and the python3 branch to master.

Jupyter notebooks are great for interactive exploring of things, but I don't know how to do the interactive grid generation tasks that way.

[hadfieldnz]

I'm sure I added a comment to this issue yesterday, but I can't see it, Perhaps I didn't save it

Renaming the branches would not be a good idea because the change would have to be propagated to all the 47 forks, or at least the active ones. Storing documents in a separate gh-pages branch seems to work fine.

I don't think there's a problem doing interactive stuff in a Jupyter notebook. You just have to turn off the inline plots. But I will check this out.

I think Jupyter notebooks would be perfect for writing a story around the existing example scripts. The notebooks themselves don't play well with version control (because of the inline images and the fast-changing metadata) but there are solutions:

• https://nextjournal.com/schmudde/how-to-version-control-jupyter
• https://nextjournal.com/schmudde/how-to-version-control-jupyter

[hadfieldnz]

That second link should be

• https://www.svds.com/jupyter-notebook-best-practices-for-data-science/

[kshedstrom]

Great, thanks for the links.