documentation

[DirkEilander]

I'm opening this issue to keep track of the documentation of GLOFRIM.

It would be could to start edition and adding to the function docstrings, especially in glofrim_bmi.py. We can than use SPHINX* and readthedocs for proper documentation. It would also be good to update the readme.md file for the glofrim v2.

• [x] update readme.md
• [x] add docstrings to functions in glofrim_bmi.py

*) SPHINX: http://www.sphinx-doc.org/en/stable/ and tutorial: https://matplotlib.org/sampledoc/index.html

[JannisHoch]

@DirkEilander I'll work on that

There are the branches "Qtests" and "csdms-compliant". Are they still both needed? Or is "Qtests" for debubbing and the other for stable versions?

[JannisHoch]

Updated the Readme.md file - please check if you're fine with the new one or whether additional changes have to be made.

Also started documentation with Sphinx in new branch "Doc". First steps taken to create html - works, only content is missing. Started with documentation with sphinx in pcr_bmi.py. Seems to work fine but still work to do.

[JannisHoch]

@DirkEilander

Added docstrings to all functions in glofrim_bmi.py 4d492a3.

Please feel free to review them, there are also one or two TODOs where I wasn't sure.

Will look now into extending the html created with sphinx.

[JannisHoch]

@DirkEilander @hii600 I have explored the functions of sphinx, autodoc, autosummary, and readthedocs.

Managed to get some good looking index.html (in _build/html) and some function docstring can be found by clicking on function names in running_GLOFRIM.html.

The documentation on readthedocs is similar, but not as good due to some reasons. First, it always used the master branch for the latest documentation, but this branch is missing all files needed to set up the documentation. You can switch to the doc-branch and it looks like the htmls, but misses the function descriptions. Guess that has to be provided somehow via requirements.txt or setup.py install. I'll look into this!

The structure and content is still very random, but open for feedback on how to proceed.

[DirkEilander]

cool you manged to setup the documentation @ChippChapp !! the readthedocs link does not yet work for me as it tries to read the docs from the master branch.

In the mean time I've updated the README file in the csdms-compliant branch and added a yml file to make installation easier. Perhaps part of my update of the README can be moved / copied to the documentation.

[JannisHoch]

@DirkEilander yeah that's what I tried to explain. You should be able to swith to the Doc branch and then see more content. Default is unfortunatley the master branch...

I will add the yml-file and README to the Doc because this is the most upstream branch. Guess we can (again) end up in quite some trouble if we add too much new files to more dowmstream branches and csdms-compliant is I guess the most downstream we have besides VU_nestedModelling.

But great initiative anyway to add a environment.yml file!

[JannisHoch]

Things to do:

• [x] Put all rst-files in separate folder

• [x] Make function docstrings available also on readthedocs.io

[DirkEilander]

It wasn't clear to me directly how to switch branches, but basically you need to change the url I figured. To save @hii600 some research: you can access our documentation under development (from the doc branch) here: https://glofrim.readthedocs.io/en/doc/#

I agree on the branches!

[hii600]

@ChippChapp @DirkEilander Although I'm somewhat behind to follow the updates going on, the documentation work looks really impressive!

[JannisHoch]

found the way to change the settings. not the "doc"branch is shown as latest, i.e. once you enter readthedocs. Less confusing I hope.

[JannisHoch]

Update: readthedocs works now properly with documentation of GLOFRIM idea, set-up, work flow, and functions.

TODO:

• [x] Extend number of functions documented

• [x] Review documentation by @DirkEilander and @hii600

• [x] Clean-up "doc" branch (i.e. all files that are not required for readthedocs)

• [x] Merge into csdms-compliant (Attention: RTD settings need to be updated!)

• [x] done.

[JannisHoch]

@hii600 @DirkEilander I have moved the LISFLOOD-FP repository from GitLab back to GitHub. Think this is more consistent with the rest of the models/code. You can find it here

[JannisHoch]

Documentation is so far on track and also the different branches are merged now. Last update of documentation once results and publication are submission ready.