document divergence matrix; clarify genetic_relatedness_matrix

[petrelharp]

Following up on my embarassing mistake in #3314, here's:

• documentation of divergence_matrix
• clarification of what exactly genetic_relatedness_matrix does,
• including some extra detailed comments in the python, recording what I figured out over in Add 'mutation' mode #3314.

Closes #2781.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.80%. Comparing base (488b02b) to head (22cdc8b).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3327   +/-   ##
=======================================
  Coverage   89.80%   89.80%           
=======================================
  Files          29       29           
  Lines       31062    31062           
  Branches     5687     5687           
=======================================
  Hits        27894    27894           
  Misses       1779     1779           
  Partials     1389     1389           

Flag	Coverage Δ
c-tests	86.84% <ø> (ø)
lwt-tests	80.38% <ø> (ø)
python-c-tests	87.05% <ø> (ø)
python-tests	98.84% <ø> (ø)
python-tests-no-jit	33.55% <ø> (ø)
python-tests-numpy1	50.10% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
python/tskit/trees.py	98.89% <ø> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.