Docathon topics for March 2017

[rjleveque]

Let's discuss possible things to do during the Docathon the week of March 6, 2017. There will be groups gathering at Berkeley BIDS and UW eScience, but some things will be webcast and people can join in from elsewhere.

I'm moving the discussion here from the claw-dev thread

• @ketch suggested: One thing we might want to consider is switching to this package for the gallery: http://sphinx-gallery.readthedocs.io/en/latest/index.html
  I don't think it supports all the functionality we want, yet. Perhaps we could also contribute to it from what we have developed for galleries.

• A related topic is how best to incorporate Jupyter notebooks into the docs. Currently we have several listed in the with the Gallery on the page http://www.clawpack.org/notebooks.html. Can we incorporate them more directly into the docs?

• Maybe someone could help us figure out how to make it easy to provide multiple versions of the documentation, e.g. to select v5.3.1 rather than v5.4.0.

• Other big issues that we could use help on from others involved in the Docathon with experience from other projects?

Please suggest other meta-topics and/or specific aspects of Clawpack that need a better documentation page.

[mandli]

Couple of thoughts:

• Enable Doxygen documentation for the Fortran incorporating this also into the existing Sphinx documentation (we would slowly add explicit Doxygen documentation to the Fortran)
• Fix weird static image problems we sporadically have

[ketch]

After more investigation I think that sphinx-gallery will not be worth our time at this point, partly because we cannot make our directory structure anything like what it expects (our docs are not even in the same repo as the code to be run) and partly because we want much more customized output than what it is designed to provide.

For incorporating notebooks into the documentation, we could use nbsphinx: http://nbsphinx.readthedocs.io/en/latest/. It would be great to add more examples in notebook format, I think.

[rjleveque]

One possible project is to write up better documentation on how the AMR algorithms work. We started this in a reading group last year and created some notes and diagrams visible on this google doc

It would be nice to turn some of this into a .rst file for the docs.

I think @xinshengqin might have a nicer flow chart now.

[mandli]

+1 to the AMR documentation. I think at the very least having an accepted (and correct) flow diagram would be great to post.

[xinshengqin]

I have a note that explains some of the global variables in amr_module.f90 and I am adding more explanation of variables into it.
I made a flow chart for part of the AMR code several months ago. Recently I am making a different flowchart since I find the old one hard to understand. Personally, I think having only a flowchart of AMR can help very little. The whole AMRclaw is a complex program with many variables. The flowchart needs to contain those variables (or many concepts in AMR if we don't use the variables in AMRclaw) in order to make it concise. So probably the best way would be having a note of explanation to every variables in the module at hand when looking at the flowchart.

[ketch]

I have added a label "docathon" to the issue tracker. I suggest that we use this thread for brainstorming, and when there is something we plan to work on we create an issue for it, apply the label, and continue specific discussion in the thread for that issue.

I have labeled #64 with "docathon" as I would like to tackle it. I think that having the docs built and published automatically every time we push would make our lives easier and encourage further contributions to the docs.

[rjleveque]

Good idea!

[mjberger]

I agree - a flow chart does not really help. But if you really want one, I suggest you use the flow chart that at least organizes the routines by “topic” - e.g. regridding,flagging, updating and conservation fixes, etc. — Marsha

…

On Feb 26, 2017, at 1:38 AM, Shawn Qin ***@***.***> wrote: I have a note that explains some of the global variables in amr_module.f90 and I am adding more explanation of variables into it. I made a flow chart for part of the AMR code several months ago. Recently I am making a different flowchart since I find the old one hard to understand. Personally, I think having only a flowchart of AMR can help very little. The whole AMRclaw is a complex program with many variables. The flowchart needs to contain those variables (or many concepts in AMR if we don't use the variables in AMRclaw) in order to make it concise. So probably the best way would be having a note of explanation to every variables in the module at hand when looking at the flowchart. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

[rjleveque]

@mjberger: you made a flow chart like this last year I think, which is still available at the google doc on AMR.

[mjberger]

yes - that is what I was referring to. IF you scroll down a bit, you will find links to AMRDiagrams and some others. — Marsha

…

On Feb 27, 2017, at 2:06 PM, Randall J. LeVeque ***@***.***> wrote: @mjberger: you made a flow chart like this last year I think, which is still available at the google doc on AMR. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.