Enable copy-pasting working example code from numpy style docstrings

[MarcSkovMadsen]

I would like to be able to copy paste working example code from numpy style docstrings. Currently I have to remove >>> and ... my self.

vs-code.mp4

For context I'm currently contributing improved docstrings to HoloViz Param and we are discussing how we can best include useful example code in the docstrings. Join the discussion holoviz/param#977 (comment).

The problem is would like our example code to be useful in VS Code with Pylance, VS Code with jedi-language-server, PyCharm, Sphinx docs, Jupyter Notebook and many more places.

[MarcSkovMadsen]

It seems jedi-language-server handles this perfectly. Both when displayed and copy-pasted.

vscode-jedi-language-server.mp4

[rchiodo]

Jedi is removing the >>> that's in the docstring. I think we'd only do that if Sphynx did it too.

This block here:
https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#doctest-blocks

[rchiodo]

An alternative would be to use code blocks. Then the >>> isn't necessary to get the code to format like code:

def foo_with_doctest():
    """
    Some example code:

    >>> print(1)
    >>> print(2)

    """

Gives you this:

While this docstring gives you this:

def foo_with_codeblock():
    """
    Some example code:

    .. code-block:: python

        print(1)
        print(2)
    """

[MarcSkovMadsen]

Thx. We are using numpy style docstrings. One of the 4 big styles in Python. Its docstrings use >>> for examples https://numpydoc.readthedocs.io/en/latest/format.html#examples. Thus it does not make sense to use other types of code blocks without switching everything else away from numpy style. And thats a lot of work for a big ecosystem like HoloViz.

[maximlt]

Jedi is removing the >>> that's in the docstring. I think we'd only do that if Sphynx did it too.

This block here: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#doctest-blocks

Selecting code in a code block on Python's website (built with Sphinx) doesn't include the prompts.

There's also an option to hide the prompts and outputs.

The sphinx-copybutton extension has a lot of knobs one can tweak, for instance, to exclude prompts for copies, which imho is what most people want (you can actually copy/paste code with these prompts in an IPython shell but that looks more like a workaround :) ). See more info on their site https://sphinx-copybutton.readthedocs.io/en/latest/use.html.

---

The good news is that there are many ways VSCode would enhance the UX of these docstrings code blocks :) !

[rchiodo]

If we want to still return the >>> in the output, VS code would need a way for us to override what happens on copy (like how the Python website does it), but I'm not sure that's possible. At least not that I could find in 'vscode.d.ts'

The other alternative would be to eliminate the >>> in the returned text. I don't think we'd want to do that for everybody though, so we'd need a custom setting to turn them off.

Transferring to a discussion item for up votes.

[rchiodo]

I actually think VS code supporting copyable-code in hover would be a better implementation. Then it would work for other languages.

Our markdown has sections like this:

```python
>>> print(1)
```

So VS code could use that to put up a custom copy button like the pandas docs do.