-
Notifications
You must be signed in to change notification settings - Fork 12
Conversion examples in the documentation and docstrings #495
Conversion examples in the documentation and docstrings #495
Conversation
docs/conversion_examples_gallery/recording_and_sorting/neuroscope.rst
Outdated
Show resolved
Hide resolved
consider using sphinx.ext.doctest |
…ttps://github.com/catalystneuro/nwb-conversion-tools into add_conversion_in_the_docstring_of_data_interfaces
Yes, I am trying to find out if this can work as I expect that we can get prettier format that way. One problem with this I am checking today if we can have |
@h-mayorquin makes sense. I would avoid downloading data in the docs build because I think we'll run up against space and time contraints on readthedocs |
…he_docstring_of_data_interfaces' into add_conversion_in_the_docstring_of_data_interfaces
OK, so now we have a pipe-line going on here. I added testing in CI and now I added some utilities so the code can be display with and without the prompt ( Right now, I have two format proposals in the neuroscope docs. Could we chose the format between these two (or any other), accept this as a template to base future examples on and I will all the other interfaces based on this, @bendichter ? |
>>> # Creates a datetime object with date the first of Junuary of 2020 in the US/Pacific time-zone | ||
>>> metadata = interface.get_metadata() | ||
>>> session_start_time = datetime(2020, 1, 1, 12, 30, 0, tzinfo=tz.gettz("US/Pacific")) | ||
>>> metadata["NWBFile"] = dict(session_start_time=session_start_time) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
>>> metadata["NWBFile"] = dict(session_start_time=session_start_time) | |
>>> metadata["NWBFile"].update(session_start_time=session_start_time) |
I prefer this syntax. The way you have it here, any fields in NWBFile other than session_start_time
would be removed. You could also do metadata["NWBFile"]["session_start_time"] = session_start_time
, but I prefer doing the dictionary update because you can assign multiple fields at once if you want to, e.g.
metadata["NWBFile"].update(session_start_time=session_start_time, notes="hello")
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Right, this makes more sense.
Done in the latest commit.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@bendichter
I just realized though, that this fails because the metadata does not necessarily have the key NWBFile
at that point in time.
docs/conversion_examples_gallery/recording_and_sorting/neuroscope.rst
Outdated
Show resolved
Hide resolved
True | ||
|
||
The other type of display: | ||
^^^^^^^^^^^^^^^^^^^^^^^^^^ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I prefer this one. I expect most users to want to copy/paste the entire code block and this makes that a bit easier.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I agree with Ben, this is a short example, I don't think it's necessary to break it down into different code blocks.
I'd also format the comments so that the scrollbar disappears
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I added the changes and now this is the only one that remains. Which scrollbar, @weiglszonja? (maybe it disappear now but I did not know what you were talking about).
docs/conversion_examples_gallery/recording_and_sorting/neuroscope.rst
Outdated
Show resolved
Hide resolved
Co-authored-by: Ben Dichter <ben.dichter@gmail.com>
Co-authored-by: Ben Dichter <ben.dichter@gmail.com>
Co-authored-by: Ben Dichter <ben.dichter@gmail.com>
Co-authored-by: Ben Dichter <ben.dichter@gmail.com>
…or corrections to the documentations for sphinx style ;
Axona, blackrock, spikegadgets, spikeglx don't have spacing between comments consistent with the other interfaces (which looks slightly better) OpenEphys doesn't have the same comment structure overall Neuroscope and cellexplorer sorting examples? |
(I think Axona also technically has a sorting interface, but it was more ad hoc as I recall so maybe skip for now?) |
@@ -0,0 +1,32 @@ | |||
Conversion Gallery |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd put this file inside the conversion_examples_gallery directory. Then all of the reference can shorten, e.g. conversion_examples_gallery/recording/axona -> recording/axona
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I was thinking on having everything that is on index.rst
(the top-level file) also in docs. The idea was the file structure would reflect the document structure.
Thanks, I align the comment structure for the former group. OpenEphys produces output by default (click on the Neuroscope and cellexplorer. Those ones are missing. |
…he_docstring_of_data_interfaces' into add_conversion_in_the_docstring_of_data_interfaces
Motivation
@bendichter mentioned in of our team meetings that it would be an idea to have a gallery of examples that we could quicly point out to the users. Also, we have issue #442 to add examples in the docstrings of non-data. This PR is to test whether it is feasible to integrate both approaches and at the same subject the docstring and the example gallery to testing suite using the capabilities provided by
doctest
:To-do:
After the gallery examples are done we can add links to each of the docstrings in their respective data-interfaces so the examples are accessible from there.