Fix some sphinx issues

[pgunn]

This PR is an attempt to fix some of the sphinx rendering issues - namely the issues with the core functions having sections but no functions/methods showing up.

It does NOT fix all the issues we're aware of, particularly the ReadTheDocs broken links for non-function-reference stuff, but those will take some thought and a redesign.

At least with the local rendering, things look good. This can be reproduced with a source tree by:

1. activating whatever environment is used (I use caibuild for my compiled caiman environment)
2. doing mamba install -c conda-forge sphinx numpydoc
3. cd docs
4. sphinx-build -M html source html
5. Point your browser at the docs generated under html/html

For iterating over errors while changing and fixing things, I replace step 4 with:

pushd .. ; pip install . ; popd ; rm -rf html ; clear ; sphinx-build -M html source html 2>&1 | less

and look for the word ERROR (and at any warnings you see, if you like).

The bulk of this is fixing fiddly comment formatting; sphinx has very particular expectations on how docstrings must be formatted for functions for them to be turned into docs, and I only somewhat understand the rules, but this gets rid of all errors I see when running locally and the functions turn up locally too.

[pgunn]

This diff changes no real functional code, so the chances of breaking something are pretty much nil. It's also what I suspect is both unobjectionable and uninteresting to anybody; will probably land this later today or tomorrow unless anyone objects; if it looks good on RTD we may do a release just to get this into the main branch there (will be a very uninteresting release, but that's okay).

[pgunn]

We'll want to verify by seeing what RTD does with this, but this should solve #997