Refactor the API Ref

[nanjekyejoannah]

@LPereira95 before I commit everything, can we go through this draft API ref for the geometry module and verify what we want before I modify the rest of the docs.

[luisfpereira]

Thanks @nanjekyejoannah!

For the changes with autosummary I agree (it is exactly what I was thinking).

One thing I wonder is if we can simplify the name in the left table of contents (e.g. if I'm within geomstats.geometry.manifold.Manifold, it suffices to have the name manifold.Manifold - and later even Manifold will suffice).

For the changes in the docstrings, please take a look to linting errors (see link below). Additionally, check in the contributing guide how you can run flake8 locally, so you can immediately see what are the (linting) errors you may introduce.

[luisfpereira]

Notice this is not allowed by linting (check e.g. here).

It is expected that the first line of the docstring contains a brief description of the class/function/method.

[luisfpereira]

When escapes are used within the docstrings, e.g. within math expressions, we need to add "r" to allow proper rendering. Notice that linting also checks it.

[nanjekyejoannah]

I have the API ref PR updated, several things:

• There is lots of fixing for doc strings, I have separated this in separate PRs
• Autosummary now shows many errors to be fixed in imports
• Notebooks has so many errors
  I know we had agreed that we will try to address all the sphinx-related errors but I am now worried if its realistic, many areas are affected and most are not related to docs.

We can chat tomorrow and scope what we can reasonably address.

[luisfpereira]

I'll close this as we decide to move in smaller steps. #1663 addresses the same issues as here.