Documentation status of classes and functions

[benjeffery]

Seeing we have now released 0.6.0 I thought it was a good time to review the documentation. I've prepared a report at https://lime-onida-78.tiiny.site/ (note that the report won't detect inheritance so for example the table base class looks undocumented)

Some initial thoughts:

We want to have undocumented methods, so yellow and red here are not "bad" - but we should be sure that this is intended. As such I think adding _ before deliberately internal methods may be useful. (These are mostly the yellow items) If you think this will be a lot of visual noise for not much gain please speak up.

The red items are where we have a docstring but it doesn't make it to the HTML documentation. This is often deliberate as we don't make early, experimental APIs documented as once something is in the HTML documentation we commit to not breaking it where possible, so this lets us iterate without that commitment.

However I'm sure we forgotten some things that are now mature, for example there is quite a bit in the combinatorics code, and things like RateMap.

[hyanwong]

For RateMap, the plan was to move the documentation from msprime. See #2679. I think we can probably just go with that now, and export the tskit rate map under the hood in msprime to maintain backwards compatibility?

[hyanwong]

Looking at this again, I wonder if we want a derived class "RecombinationMap", that inherits all the rate map stuff but also has read_hapmap (and maybe write_hapmap). We could then also have a genetic_to_physical and a physical_to_genetic, like we used to, which can also be handy.

[jeromekelleher]

Sounds like a reasonable plan

[benjeffery]

@jeromekelleher and I had a recent discussion about this. We thought it best if we explicitly export in the tskit __init__.py those methods and classes that are part of the API, documented or not. We don't want to break anyone's code so will have a fallback for those things that aren't explicitly imported.

[hyanwong]

As such I think adding _ before deliberately internal methods may be useful. (These are mostly the yellow items)

Do you want me to add these to the things which I know for sure are internal, such as SvgTree.assign_x_coordinates()?

[benjeffery]

Not yet, having looked at how many there I think we'll use explicit export to indicate a method is non-private. It will be too much visual noise to have _ everywhere.

[petrelharp]

Wow, that's very useful. I see a fair number of yellow things are used-to-be-in-the-API-but-deprecated.