Added plotly_intercept_code configuration option

[Davide-sd]

There are use cases where a Plotly figure is being generated by a user defined class and shown through one of the class methods. For example, one of the commands in my module might be:

plot(sin(x), (x, -10, 10))

The function plot returns a custom Plot object, containing the Plotly figure. Inside the plot function, the Plotly figure will be shown before the return statement.

With the current implementation of this extension it is impossible to visualize the resulting plot. Plotly doesn't have something similar to Matplotlib's figure managers, which "intercepts" the figures being shown at a lower level.

Solution: create a new configuration option, plotly_intercept_code, which will eventually be set to a user-defined function, accepting the current code-block being processed and returning a modified code. The user can modify the code with regex or ast to extract the Plotly figure from the custom objects. Then, the current implementation will be able to continue successfully.

Consider the following code-block example contained into a docstring. If a user executes it, it will show a Plotly figure.

fx = lambda u, v: (4 + np.cos(u)) * np.cos(v)
fy = lambda u, v: (4 + np.cos(u)) * np.sin(v)
fz = lambda u, v: np.sin(u)
plot3d_parametric_surface(fx, fy, fz, ("u", 0, 2 * pi), ("v", 0, 2 * pi),
    rendering_kw=dict(
        contours={
            "z": {"show": True, "start": -1, "end": 1, "size": 1/10,
                  "width": 1, "usecolormap": True}
        },
        showscale=False, colorscale="Aggrnyl"),
    zlim=(-2.5, 2.5), title="Torus", backend=PB)

If this extension executes the above code block, it will open the plot on a new browser window, but it won't be able to include the figure in the docs, because it doesn't know where the figure is actually stored.

With this commit, the extension processes this code block, send it to the "intercept code function", where I can use the ast module to modify the code to:

fx = lambda u, v: (4 + np.cos(u)) * np.cos(v)
fy = lambda u, v: (4 + np.cos(u)) * np.sin(v)
fz = lambda u, v: np.sin(u)
myplot = plot3d_parametric_surface(fx, fy, fz,
    ("u", 0, 2 * pi), ("v", 0, 2 * pi),
    rendering_kw=dict(
        contours={
            "z": {"show": True, "start": -1, "end": 1, "size": 1/10,
                  "width": 1, "usecolormap": True}
        },
        showscale=False, colorscale="Aggrnyl"),
    zlim=(-2.5, 2.5), title="Torus", backend=PB, show=False)
myplot.fig

Here:

1. I assigned the object returned by the plot command to a variable.
2. I added show=False to the plot command, so no figure will be shown on the browser (which is annoying if you have dozen of figures opening every time you build the docs).
3. I added a new command extracting the Plotly figure from my custom object.

Once this modified code is returned, it will be normally processed by this extension and everything works as expected.

[Davide-sd]

@harupy Please let me know if you intend to merge my pull requests and eventually update the package to a new version...