Pvlib-python: Add examples to docstrings

[bmu]

We should decide whether we want to add examples to the docstrings of the functions or not.
While (I think) examples are not included in every pandas object, they are in numpy. numpydoc has an _optional_ section for examples.

I would like to include examples and also I would like to use doctests.
For the moment we have some examples, but some doctests fail
(see output of nosetests -v -w pvlib --with-coverage --cover-package=pvlib --with-doctest).
I once had a discussion with pandas developers (see pydata/pandas#3439) and they didn't see their examples as tests.
However for pvlib, doctest may have an additional benefit for testing purposes and also it tests if our documentation is up to date with the state of the objects we document.

[wholmgren]

We definitely need more examples in the docs. I don't know if we need an example for absolutely everything, though. In any case, we probably will want to change the documentation formatting to 1 page per function.

I don't have any experience using doctest, but I'm ok with trying it out. I would say that we should not rely on doctest for anything other than ensuring that the docs are up to date with the library, and that anything that is in a doctest should be in the main tests.

[mikofski]

Any decision on this?

[wholmgren]

@mikofski I support adding brief examples to the function docstrings where they would be useful. Personally, I find documentation pages structured like ModelChain and Clearsky to be more useful, so that's where I've focused my documentation efforts. But I encourage people that want small examples for each function to take on the effort. So I lean toward leaving this generic issue open. What do you think?