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:

For example::

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

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

[jreback]

@cpcloud interesting....

[cpcloud]

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

[jorisvandenbossche]

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).

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

[jtratner]

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"

[jtratner]

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.

[jtratner]

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

[jtratner]

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

[cpcloud]

@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//issues/3430#issuecomment-25413656
.

[jorisvandenbossche]

@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 >>>)

[jtratner]

@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.

[jorisvandenbossche]

@y-p voila, quickly did a PR