Restructure documentation, port tutorials

[dacoex]

This is the code for #120. Based on the pvsystem branch by @wholmgren

The last commit now has a potential ToC as a list.

I think discussing using the list is easier and less effort.
Let's agree ToC level by ToC level.

To revewi, please also look at the RTD version:
Contents (potential new ToC)

[wholmgren]

I'd remove the top level "Examples".

[dacoex]

Was mimicked after
http://xarray.pydata.org/en/stable/index.html
http://xarray.pydata.org/en/stable/examples.html

[wholmgren]

I see. I don't have a strong preference here.

[dacoex]

I suggest to keep the top level.
This helps to reduce maxdepth to 1 once there are many sub-pages.

[dacoex]

So it seems that we are set with the ToC for now?

[wholmgren]

Yes, with the understanding that we'll probably want to change some of it once we start to see the content.

[dacoex]

Sure. Seems stepwise is a better approach....

[dacoex]

@wholmgren I am likly to pick this one up step by step because I wanna see the system tut in.
Would you still agree to port the essential notebook based tutorials to python code / doctest so that they can be tested through an api restructuring as it happened with v3.0?

[wholmgren]

The documentation has grown since this conversation started. I would like to see more documentation pages similar to our Time and time zones, Clearsky, and Forecasting pages. Transposition and solar position pages would be relatively straightforward to write. I think a good ModelChain page is very important, but more work. I recommend closing this PR and doing these (or something like them that you care more about) one PR at a time.

[dacoex]

Thanks for responding.

Currently, my preference is with the pvsystem tutorial initiated by @jforbess

I would like to see more documentation pages similar to our Time and time zones, Clearsky, and >Forecasting pages.

This is what I was planning to convert the existing notebook into.

May question now:
How do we ensure that the code in the documentation always up-to date?
Is it included in the tests?

This shall be there to ensure that we do not damage the docs when refractoring the api of the core lib.

e.g. there are soem error in http://pvlib-python.readthedocs.io/en/latest/forecasts.html

Some guidance would be appreciated before writing new pages.

Regarding ToC & structure, I see that in future there may be the followings technical pages:

- Fundamentals & Basics
   |---- Time and time zones
   |---- Clearsky
   |---- solar position
   |---- Transposition 
   |---- Input data
           |---- US TMY
           |---- Forecast & weather model (the whole section of Accessing Forecast Data to Weather Models deal with getting data)
           |---- other providers
           |---- local measurement & SCADA data (link to https://github.com/sandialabs/pecos )
- Modelling & Simulations
   |---- Trackers
   |---- Complete PV system
   |---- Sensitivity studies
   |---- Forecasting 
   |---- Cross-comparison & validation with other tools
   |---- etc.
- Analysis & Presentation
   |---- Statistisc ( ... should create a feature request issue because nothing there yet)
   |---- Plotting 
   |---- Reporting ( ... pvlib could be used to create a report like: 
                                http://solargis.com/assets/sample/SolarGIS-pvPlanner-sampleReport.xls
                                http://solargis.com/assets/sample/SolarGIS-pvPlanner-sampleReport.pdf) 

[wholmgren]

I've never written any doctests but I think you can do them in ipython directive. It will be a lot of work, so good luck. As I said before, go ahead and write up one new page in a new pr.

I've explained the error on the forecasting page multiple times.

[dacoex]

I've never written any doctests but I think you can do them in ipython directive. It will be a lot of >work, >so good luck.

As alternative, we could use a separate code file being test & then use it as listing in the Spinx docs.

[wholmgren]

http://matplotlib.org/sampledoc/ipython_directive.html

.. ipython::

   In [1]: x = 'hello world'

   # this will raise an error if the ipython output is different
   @doctest
   In [2]: x.upper()
   Out[2]: 'HELLO WORLD'

[wholmgren]

There are some useful ideas in the discussion above, but the way to make progress at this point is starting and finishing one small PR before moving on to the next.