Math docs are inconsistent and have broken links

[canyon289]

Description of your problem

The docs for the math api have inconsistent or broken links. For invlogit links to method documentation but none of the rest do. Sigmoid seems to be missing its api docs entirely. The definition of abs links to nothing.

https://docs.pymc.io/api/math.html

Desired State

All math methods are documented and link to the full method documentation

[rpgoldman]

Also the format of the docstrings is wrong.

I don't actually know how the :autosummary: command is supposed to work, so don't know why it's output is so messed up (where did all those escaped asterisks come from?).

[golanor]

Is this related to #3879 ?

[fonnesbeck]

Just noticed the docstring formatting. For some reason, the first one is often correct, but subsequent ones are missing the colon and spacing:

[rpgoldman]

@fonnesbeck That mis-formatting is all over the docs. I conjecture that what happens is that somewhere in reading files sphinx goes off the rails and from then on it does this wrong.

I have not been able to figure this out because:

1. It doesn't seem to trigger any error reporting
2. The order the files are output does not necessarily parallel the order they are read, which makes it hard to tell where sphinx gets lost reading. I think it reads a bunch of stuff and then dumps it as directed by the .rst, which makes tracking the parsing very hard.

I used to think it was getting confused because of the use of var: type instead of var : type but now I suspect it's something else -- the spacing of the colon doesn't seem to predict correct or incorrect typesetting.

[fonnesbeck]

Mighr be the space before the colon, yes. I recall using that before. Maybe check on a site where things are working.

[rpgoldman]

I'm afraid it's not that in any simple way -- some places with the single space are formatted correctly, and some with the correct spacing are formatted wrong, and vice versa. I'm at a loss to know how to fix this. Probably need to work up from very small documents to see where it goes wrong.

[OriolAbril]

This was fixed in #5439.

As a side note, on the colon spacing issue that I have seen mentioned in several other issues too, the colon should be both preceded and followed by a space. There was a bug in the old v3 theme that didn't render things correctly when doing things right, but removing the space wasn't really fixing things. It was only breaking numpydoc parsing and telling sphinx everything was the parameter name instead of being name followed by type info. As shown in #5459 things are rendered correctly and significantly better when using the v4 (working) theme and the spaces before and after the colon.