Improve ease-of-use of code in the User Guide

[colleenjg]

Problem: The current formatting code in the user guide adds a barrier to easily copying and running the example code. See the Meet the Data Objects section, for example.

If the top-right corner copy button is used, chevrons and ellipses are copied alongside the code. They then have to be removed for the code to run

>>> import numpy as np
>>> from torch_brain.data import RegularTimeSeries

>>> behavior = RegularTimeSeries(
...     sampling_rate=100.0,  # in Hz
...     hand_vel=np.random.randn(1000, 2),
...     eye_pos=np.random.randn(1000, 2),
...     pupil_size=np.random.randn(1000),
... )

Alternatively, if the code is selected and copied, the chevrons and ellipses are ignored. However, printed outputs are still copied and they have to be manually removed to run the code. Relatedly, once the code is copied into a single notebook cell, lines like behavior only work as intended (approximately as print(behavior)) if they are the last command in the cell.

Solution: I'm not sure yet, but I'll look into a few options.

Ideally we want to maintain the current benefit of showing example outputs in a compact and clear manner, as achieved by:

>>> behavior
RegularTimeSeries(
  hand_vel=[1000, 2],
  eye_pos=[1000, 2],
  pupil_size=[1000]
)

However, we also want the code to be easily copied and run in a notebook, producing equivalent outputs to what is observed in the guide.

Relevant questions:

1. Do you mind if there are more code blocks that can be copied? That would provide a solution to making lines like behavior functional, and still showing the output right below in the guide. The main alternative I see would be to use more elaborate print statements (e.g., print(f"behavior:\n{behavior}")), and then showing all outputs together each block of code.
2. Do we want users to be able to download guide pages like this one as notebooks, so they can actively interact with the code?

[milosobral]

I totally agree that we should "support" both ways of interacting with guides: reading and copy pasting the code and running it. I think PyTorch does a good job there. Maybe we could take inspiration from that?

[vinamarora8]

Hi! The sphinx-copybutton extension seems to have a way native to resolve this with a small configuration change. With #341, the copy-button should work as you expect. Lmk if you expect something different!

[colleenjg]

This is great - I think it gets us most of the way there.

The last element to consider is that a user still won't automatically get the displayed outputs when they run the code. A solution to this would be to add slightly descriptive print statements, e.g.:

For example:

import numpy as np
from torch_brain.data import RegularTimeSeries

behavior = RegularTimeSeries(
    sampling_rate=100.0,  # in Hz
    hand_vel=np.random.randn(1000, 2),
    eye_pos=np.random.randn(1000, 2),
    pupil_size=np.random.randn(1000),
)

# Printing the object shows the shapes of the underlying data
print(f"Behavior: \n {behavior} \n")

# length represents the number of timepoints
print(f"Time series length: {len(behavior)}\n")

# timestamps are automatically created from the sampling rate
print(f"First 10 timestamps: \n {behavior.timestamps[:10]}\n")

Output:

Behavior: 
 RegularTimeSeries(
  hand_vel=[1000, 2],
  eye_pos=[1000, 2],
  pupil_size=[1000]
) 

Time series length: 1000

First 10 timestamps: 
 [0.   0.01 0.02 0.03 0.04 0.05 0.06 0.07 0.08 0.09]

Here, I've done it like in the pytorch example Milo linked above, where the output is shown separately from the input. We could instead interleave it, though, as is currently the case.

This would be a bigger change, though, so I think we should go ahead and already merge your PR as it really handles the main issue.

[vinamarora8]

Reopening this as it is not fully resolved by #341