Document divergence_matrix

[jeromekelleher]

Following up on #2736, we need to document the function.

Note that I left the old partially implemented version of divergence matrix as a commented out block here as it could be a useful starting point. We should delete that as part of closing this issue.

Maybe be worth doing #2780 first.

[jeromekelleher]

Also add to CHANGELOG when documenting

[jeromekelleher]

@petrelharp should we document this for the upcoming release? There's some nice stuff on parallelisation that would be helpful for the downstream code in genetic_releatedness_matrix which is currently undocumented. Would be good to document this once, and then just refer back to the ts.divergence_matrix documentation for reference.

[jeromekelleher]

Here's the code for reference. I think we have an old version commented out immediately above, so the main job in terms of documentation would probably be describing the parallelisation stuff (which is fairly straightforward?)

[benjeffery]

@petrelharp This is the last issue for 0.6.1 - shall we leave things undocumented to get it out?

[petrelharp]

This is going to involve a bit of work because to do this properly we need to introduce mode="mutation", which is what the thing we currently call "site" mode actually does. Rather than rush that (and given my other homework at the moment), I would like to postpone to the next release.

[jeromekelleher]

OK, let's park for now.