API docstrings in readthedocs

[CodyCBakerPhD]

@sneakers-the-rat is proposing to use an automatic documentation method to put the docstrings for each function (in each interface) in the documentation so people can search for things that way.

Is your feature request related to a problem? Please describe. A user wants to look up details on function arguments, but can't or doesn't want to type nwb_conversion_tools.location.function_name? in an python environment.

Describe the solution you'd like Add the arguments and docstring details to the readthedocs on the web, so people can use the search functionality and ctrl-f.

Describe alternatives you've considered Now, we should note that docstrings for class functions pass to inheritors automatically in current versions of python. Hence, we've intended for only the highest-level docstrings to include the richest most detailed docstrings for things like run_conversion, get_metadata, etc. but I admit we're probably not where we would like to be on that (also a different issue altogether there). But point being, we wanted the docstrings to really be felt top-down, so that anyone could go look for docstrings on a particular interface by simply using the nwb_conversion_tools.location.function_name? method.

One case where this breaks is if the run_conversion function has been overridden and additional arguments included, which we mostly did for older projects like the Mease lab to include custom things like the timestamps. Those were so valuable however that we ended up just integrating it into a big refactor of spikeextractors, so it's now in the base behavior regardless. But conceptually, a particular format interface might need some additional arguments at a particular stage, possible requiring user input, so those docstrings would always have to be updated, meaning there would also be deviations from the upstream classes at that point.

@luiztauffer Automatically generating the docstrings for availability on a 'API' subheader of the main docs would allow people to just go to their format directly to learn about the arguments, but it would result in a lot of text duplication since most interfaces will have the exact same . I'm not sure if it's worth the tradeoff, especially since NWB-conversion-tools is supposed to be very user friendly for people perhaps not so interested by such things and it's mostly devs who would want to discover various optional arguments, but I could be wrong about that as well. What's your opinion on that part?

Checklist

• [X] Have you ensured the feature or change was not already reported?
• [X] Have you included a brief and descriptive title?
• [X] Have you included a clear description of the problem you are trying to solve?
• [X] Have you checked our Contributing document?

[CodyCBakerPhD]

Moving forward on this!

[sneakers-the-rat]

I think i might be misunderstanding this issue, but if you don't want to duplicate a bunch of text manually for eg. child objects with inherited methods that sounds like the inherited-members option in autodoc? but again i'm probably not understanding the issue.

[CodyCBakerPhD]

No issue, moving forward on this!