STY: Reword first lines of example.py docstrings

[justinludwig]

Running doc/example.py through pydocstyle
using the "numpy" conventions turns up the following violations for the
module docstring:

• D205: 1 blank line required between summary line and description
  (found 0)
• D400: First line should end with a period (not 'd')
• D404: First word of the docstring should not be This
• D415: First line should end with a period, question mark, or
  exclamation point (not 'd')

And the following violation for the foo() function docstring:

• D401: First line should be in imperative mood; try rephrasing (found
  'A')

This change slightly rewords the first line of both docstrings to better
model how docstrings should begin:

1. It reformats the module docstring to place the first sentence on its
   own line, and remove the superflous "This is the" introduction.
2. It rewords the foo() function docstring to rephrase the first line
   as a command (following the PEP 257 convention).

After this change, pydocstyle finds no violations.

[larsoner]

@justinludwig it might be useful to add a check to Travis that it complies. Do you want to try adding it here? If not, okay for me to push some commits to your branch?

[justinludwig]

it might be useful to add a check to Travis that it complies. Do you want to try adding it here?

Sure, I'll try adding that.

[justinludwig]

it might be useful to add a check to Travis that it complies. Do you want to try adding it here?

I added a line to the travis script to run pydocstyle on the example.py file -- @larsoner is that what you had in mind?

[larsoner]

Yep, eventually we should probably do the whole numpydoc module but this is a good start. Thanks @justinludwig