Add automated interface documentation

[apcraig]

There was some discussion in CICE #378 about generation of interface documentation. Several options were put forward including Doxygen, sphinx extension, or Ford. There may be others to consider.

I think there are several things to consider

• what is covered.
• what is the audience.
• what the documentation looks like.
• where the documentation ends up (on github, in readthedocs, on a separate web page?)
• how the documentation is updated.
• automation capability. can the documentation be updated automatically with each PR, like what we do with readthedocs now
• long term viability. is the tool likely to exist and be robust in the future.

At a minimum, I think we need a document for the public Icepack interfaces for the community that the community can reference. Separately, we might also want a document for the entire Icepack and CICE codes, but that seems to cover a different audience.

[phil-blain]

I'd be happy to help with that.

[apcraig]

I spent a bunch of hours playing with sphinx fortran. I finally got it to work on my local computer after messing around with various versions of things. I needed to use python3 (because that's needed for readthedocs) and I had to download and build sphinx fortran directly, in part because the public pip version is several years old and only works with python2. I believe the official version is https://github.com/VACUMM/sphinx-fortran.git, but it doesn't really seem to be actively supported. I even forked that repo thinking we might generate our own version. In the end, I think there are too many issues. sphinx-fortran (at least the version I was looking at) does not seem to be well supported in the community and I could not get it to work in readthedocs (in part because I have to manage the sphinx-fortran build manually). The other issue is that the output is not ideal. I have attached a sample pdf taken from my local implementation.

spxfor.sample.pdf

I don't like the [] in the argument lists for optional arguments. The optional attribute is also being dropped from the argument documentation. The arguments are then divided into parameters and options and how those are defined is not consistent with how we want to present the arguments. Finally, the parsing is relatively robust, but not perfect. I had to mess around with the formatting a bit in a few files, and I still could not get one of the files to be included without error. I tried to play around with the package implementation, but the package is fairly complicated. It also relies heavily on autodoc which is another part of sphinx that we might have to mess around with. It's too bad because it's pretty close and seems to have promise. If we could control the formatting a bit and get it to work on readthedocs, I think it could work well. We can actually document just a subset of methods (which is really what we want). But in the end, not unlike codecov and some of the web based test output tools, it doesn't actually work well enough (in my opinion) nor quite meet our needs. And I'm not sure it makes a lot of sense to spend resources to implement our own custom version. I fully acknowledge that someone with more python expertise might have more success than I did, and I'm not against pursuing this in general if we can get it to work. I'm just not convinced, from my experience, that it's the most efficient way forward right now. Again, I would love for this to work for us.

For the short term, I have created a small script that extracts the interfaces from the source code and drops it into the user guide. See #284. That addresses the requirement for the public interface documentation. It does not address a possibly separate issue which is to have a copy of the entire source code that is interactively searchable on the web. I'm not convinced that is important, but we can discuss that point further.

In either case, we should make some attempts to update the inline interface documentation to clarify both the purpose of the interfaces as well as the arguments. Having said that, our current implementation isn't too bad as a starting point.

[apcraig]

I believe this is addressed by #284 and has been documented. I am going to close this. If there are other issues like doxygenating the whole code or upgrading the implementation, we can create a new issue.