Identify example code blocks in docstrings and wrap in backticks

[douglasdavis]

This PR adds a regex search for >>>, capturing all text until the next double newline and wraps the matches in backticks such that example blocks use markdowns code block syntax

Before:

>>> a = '5'
>>> a
5

>>> b = 5
>>> c = 10
>>> b + c
15

After:

```python
>>> a = '5'
>>> a
5
````

````python
>>> b = 5
>>> c = 10
>>> b + c
15
```

[krassowski]

You might be interested in the test cases in https://github.com/krassowski/docstring-to-markdown (also see #22).

[douglasdavis]

Thanks for pointing me to docstring-to-markdown! Looks like the logic doesn't capture lines that don't start with >>> but immediately follow a line that does (and all >>> prefixes are dropped)

teststr = """
Examples
--------

>>> a = '5'
>>> b = 3
>>> b
3

>>> x = 'abc'
>>> x
abc

"""

convert(teststr) yields:

#### Examples


```python
a = '5'
b = 3
b
```

```
3
```


```python
x = 'abc'
x
```

```
abc
```

[krassowski]

This is intended to accommodate non-code outputs of doctests. Consider the following:

>>> print 'Python-specific usage examples begun with ">>>"'
Python-specific usage examples begun with ">>>"
>>> print '(cut and pasted from interactive sessions)'
(cut and pasted from interactive sessions)"""

You do not want the output text to be color-highlighted because it is not Python syntax.

No strong opinion on dropping/non-dropping the ">>>" but I guess more Markdown parsers will highlight Python correctly if it is dropped (plus it saves space).

[douglasdavis]

You do not want the output text to be color-highlighted because it is not Python syntax.

Yea I see what you mean, I pretty much exclusively use the numpydoc style which is where I was getting inspiration.

No strong opinion on dropping/non-dropping the ">>>" but I guess more Markdown parsers will highlight Python correctly if it is dropped (plus it saves space).

Same thing as above, I was thinking in numpydoc style!

Unfortunately there's the existence of both rst code-block:: and the Example block >>> style. I wonder how non trivial it would be to support both. Too bad there's not a single python docstring style 🤷‍♂️. the sphinx code to handle all of this is definitely not short!

[krassowski]

Literally the reason I created docstring-to-markdown ;)

[krassowski]

There is also https://github.com/Carreau/papyri being worked on and it might turn up to be a good intermediary to convert docstrings to markdown, but I have not had time to evaluate it recently.

[krassowski]

This will lead to unexpected results with the following snippet:

print(format_docstring("""
Test docstring with two examples

>>> example

>>> example 2 should work too
"""))

Result:

Test docstring with two examples

```python
>>> example
```

```python
>>> example
``` 2 should work too

[ccordoba12]

Closing in favor of PR #80.