Make the methods documentation work better

[DanHickstein]

Following up on #286, I tried looking at our documentation while putting myself in the shoes of a new user. Mainly, I was concerned with this: how would I find information about each transform method?

So, I would start by looking at the docs for abel.Transform. Here, we have very short descriptions for the method argument. These summaries generally just say the authors of the method, which is not particularly helpful. If we only have one sentence to describe the methods, shouldn't we give some most useful information about the usage? Also (and I know this will be controversial), should we give some idea about which methods are most recommended? Currently we just list them in alphabetical order. Most importantly, we need to include links for the users to get more information.

Next, if the user happens to scroll down in the abel.Transform docs (not guarenteed), then they will find this Notes section which provides some additional information about the transform methods. This Notes section seems like a bit of a duplication (in intent, not in content) of what we are doing in our Transform Methods doc.

We also have a dedicated .rst file for each transform method. Finally, we have the docstring for the individual transform method.

So, for basex, I can find information in many places:

1. abel.Transform method docstring.
2. abel.Transform Notes section of docstring.
3. Transform Methods doc.
4. basex.rst.
5. basex computational details
6. abel.basex.basex_transform docstring

And few of these are linked together with hyperlinks.

We should think more carefully about how we structure the docs to make information easier for users to find. I think that I would suggest the following:

1. In abel.Transform, I would eliminate the Notes section. In the section describing the method keyword, we add a link to transform_methods.rst. We also write more helpful (maybe 2-3 sentence) descriptions for each of the transform methods. Also, each method should include a link to it's .rst doc file and a link to the docs for the individual transform function.
2. We improve transform_methods.rst, incorporating any good bits from the abel.Transform docstring notes section. Again, this doc should include links to both the specific .rst files (already there) and the docstrings for the individual transform methods. (in addition, this doc should link back to abel.Transform, to remind people to use that instead of the individual transform methods.)

Thoughts?

[DanHickstein]

Oh, I just realized that we still had this Wiki: https://github.com/PyAbel/PyAbel/wiki

That should certainly die completely and be replaced with a link to the docs.

[MikhailRyazanov]

@DanHickstein, do you want to keep this open as a reminder to clean-up abel.Transform “Notes”? Or it already looks fine, and this can be closed?

[DanHickstein]

Yes, let's keep this open as a reminder to clean up the Notes section. I think that we should basically remove that section and replace with a link to the comparison article that we just included.

[gh4ag]

I think the documentation about the Tikhonov regularisation could be made more explicit. The reg parameter is a bit hidden and the argument transform_options only work with basex. I would recommend to handle it as an optional kwarg.