Repository: pandas-dev/pandas

Issue:
Go through package docstrings and markup code snippets as such
Noted by @karmel in #3422, sphinx supports syntax highlighting/code
quoting in code (ReST) docstrings using double colon + new line:

``` rst
For example::

            make_axis_dummies(panel, axis='major',
                              transform=lambda d: d.weekday())
```

sphinx 'autodoc' will pick these up and make code look nice.



Discussion:
@cpcloud interesting....

this seems more like an ongoing thing ... although maybe there aren't that many... really no easy way 2 tell if some part of string is valid python code in a big blob of text

This is indeed the common Sphinx syntax, and it can also be used in the other documentation (like in the whatsnew). Instead of:

```
.. code-block:: python

   some code
```

you can just use:

```
::

   some code
```

since the python highlighting is the default one (see [here](http://sphinx-doc.org/markup/code.html)).

## 

But back to the issue: I think there will indeed be very little of this cases, and even then in a lot of cases an example should be included in the example section of the docstring (and then this `::` is not needed).

I quicky went over the docstrings (only the ones that are included in the api docs), and I found two obvious cases of `codeblock` that can be removed, and none of code that wasn't highlighted and should be:
- `read_html`: https://github.com/pydata/pandas/blob/8ac0e11b59b65f0ac898dca2beebde5f87836649/pandas/io/html.py#L778
- `isin`: https://github.com/pydata/pandas/blob/1d11d8aed6c1fdc36112ec9e56273ea3b6967ba6/pandas/core/series.py

I'd prefer to change everything to use the doctest syntax, because it's neater for reading (though it does creating havoc for linting :-/) The skiprows stuff is phrased poorly. It should really just be "Note that: `skiprows=0` is equivalent to `skiprows=None`"

otherwise, better to change to doctest syntax because it's more succinct, i.e., change this:

```
       .. code-block:: python

           attrs = {'id': 'table'}
```

to 

```
    >>> attrs = {'id': 'table'}
```

And it should be highlighted appropriately.

especially in isin, this would be better than the existing, because it's much cleaner and neater. (hopefully sphinx handles this correctly - doctests are a pretty common thing in Python)

```
       The sequence of values to test. Passing in a single string will
            raise a ``TypeError``:

                 >>>  from pandas import Series
                 >>> s = Series(list('abc'))
                 >>>  s.isin('a')
                 Traceback
                     ....
                 TypeError(whatever message)

            Instead, turn a single string into a ``list`` of one element:

                 >>> from pandas import Series
                 >>>  s = Series(list('abc'))
                 >>>  s.isin(['a'])
                 Whatever output that has
```

Plus if we were really fastidious, we could actually test the doctests when they were used - e.g. with sphinx doctest extension - http://sphinx-doc.org/ext/doctest.html

@jtratner You don't like my `skiprows` documentation!? :P `read_html` was
my first PR; I was probably a bit over the top with documenting things.
I'll clean it up in my `read_html` refactor.

## 

Best,
Phillip Cloud

On Mon, Sep 30, 2013 at 6:55 PM, Jeff Tratner notifications@github.comwrote:

> Plus if we were really fastidious, we could actually test the doctests
> when they were used - e.g. with sphinx doctest extension -
> http://sphinx-doc.org/ext/doctest.html
> 
> —
> Reply to this email directly or view it on GitHubhttps://github.com/pydata/pandas/issues/3430#issuecomment-25413656
> .

@jtratner I tested it and indeed with adding `>>>` it is formatted well by Sphinx (then the `::` are not needed, even indentation is not needed when using the `>>>`)

@cpcloud far easier to edit somebody else's work than to write it yourself.
:)

Given joris's earlier comments, I'll close this as meh. 
If someone has a PR to submit. do.


Resolving patch:
diff --git a/pandas/core/series.py b/pandas/core/series.py
--- a/pandas/core/series.py
+++ b/pandas/core/series.py
@@ -2094,21 +2094,8 @@ def isin(self, values):
         ----------
         values : list-like
             The sequence of values to test. Passing in a single string will
-            raise a ``TypeError``:
-
-                .. code-block:: python
-
-                   from pandas import Series
-                   s = Series(list('abc'))
-                   s.isin('a')
-
-            Instead, turn a single string into a ``list`` of one element:
-
-                .. code-block:: python
-
-                   from pandas import Series
-                   s = Series(list('abc'))
-                   s.isin(['a'])
+            raise a ``TypeError``. Instead, turn a single string into a 
+            ``list`` of one element.
 
         Returns
         -------
@@ -2122,6 +2109,26 @@ def isin(self, values):
         See Also
         --------
         pandas.DataFrame.isin
+
+        Examples
+        --------
+
+        >>> s = pd.Series(list('abc'))
+        >>> s.isin(['a', 'c', 'e'])
+        0     True
+        1    False
+        2     True
+        dtype: bool
+
+        Passing a single string as ``s.isin('a')`` will raise an error. Use
+        a list of one element instead:
+
+        >>> s.isin(['a'])
+        0     True
+        1    False
+        2    False
+        dtype: bool
+
         """
         if not com.is_list_like(values):
             raise TypeError("only list-like objects are allowed to be passed"
diff --git a/pandas/io/html.py b/pandas/io/html.py
--- a/pandas/io/html.py
+++ b/pandas/io/html.py
@@ -759,20 +759,16 @@ def read_html(io, match='.+', flavor=None, header=None, index_col=None,
         This is a dictionary of attributes that you can pass to use to identify
         the table in the HTML. These are not checked for validity before being
         passed to lxml or Beautiful Soup. However, these attributes must be
-        valid HTML table attributes to work correctly. For example,
-
-        .. code-block:: python
-
-           attrs = {'id': 'table'}
-
+        valid HTML table attributes to work correctly. For example, ::
+        
+            attrs = {'id': 'table'}
+        
         is a valid attribute dictionary because the 'id' HTML tag attribute is
         a valid HTML attribute for *any* HTML tag as per `this document
-        <http://www.w3.org/TR/html-markup/global-attributes.html>`__.
-
-        .. code-block:: python
-
-           attrs = {'asdf': 'table'}
-
+        <http://www.w3.org/TR/html-markup/global-attributes.html>`__. ::
+        
+            attrs = {'asdf': 'table'}
+        
         is *not* a valid attribute dictionary because 'asdf' is not a valid
         HTML attribute even if it is a valid XML attribute.  Valid HTML 4.01
         table attributes can be found `here


Test patch: