chunkedgraph module documentation improvements and standardization

[bdpedigo]

Summary

• Added documentation for some returns which have a dictionary with many fields or dataframe etc.
  • This was my main reason for this PR, as a new user I just found the meaning of many of these kinds of returns opaque.
  • This could probably still be improved. I took a stab at documenting these fields but if I could be wrong, feel free to add corrections.
• Made everything use numpydoc, previously it was a mix
• Used a more standard way of specifying types (see numpydoc)
• Clarified references to actual variables in the docstrings with backticks
• Added a few missing param descriptions
• Tried to standardize nomenclature a bit, at least in this module

TODO

• fix remaining inline TODOs about clarifying units
  • asked for feedback on a couple
• build docs locally to test

[bdpedigo]

this command didn't work for me (even with a non-zero user_id, so an admin would need to fill this out.

perhaps also worth clarifying who can use this function at all?

[fcollman]

good point

[bdpedigo]

Bethany also had the same issue as me - I could open a new issue if this is meant to be available to everyone as the docs currently indicate, or if not, we could clarify here.

Although, if user info is not meant to be accessible to everyone, this info is available in the tabular changelog, so there's already a clunky workaround

[bpdanskin]

current user of the clunky workaraound

[sdorkenw]

We were conservative in what we made available to users to easily follow other peoples work. I think a discussion can be had whether this should be behind admin privileges. For giving the necessary privileges: It is easy to add dataset-specific admins, so it would be straightforward to add the two of you as that (and we should do that). While the data is available in tabular changelogs, one would still have to iterate through all neurons to trace another users actions.

[bdpedigo]

that's fair. for the purposes of this PR, I just added a note to the documentation indicating that this is only supported for admins.

separately, yes, I'd be happy to 1) get access but more importantly 2) talk about opening up this function. I don't care too much, but since there's already a roundabout way to get that info it seems like it would make sense to support for any user (or closing that loophole if not).

[bdpedigo]

I think I've addressed everything - but lmk if any further changes are requested