Port notebook tutorials to rst with doctests

[dacoex]

In conjunction with Location demotion and PVSystem/LocalizedPVSystem/ModelChain addition but now as separate issue:

The Ipython Directive could be used.

I'm using it in the new docs, so I don't understand why you're saying this.

I think the original intention with notebooks was to offer quick interactive exploration.
But now we find it hard to keep them updated and tested.
Below a way which might help

• integrate the notebooks into testing, tools: RunNotebook, see also [yt-dev] Documentation and Testing
• update and enhance the documentation to include the features of Location demotion and PVSystem/LocalizedPVSystem/ModelChain addition #93
• add system modelling tutorial, as in Tutorial: system modeling #84 but adapted to the changes in Location demotion and PVSystem/LocalizedPVSystem/ModelChain addition #93

[wholmgren]

First, we need a new name for this issue. It sounds like what you really want is something along the lines of "Port notebook tutorials to rst with doctests". Whether or not it makes it into version 0.3 (not 3) is another matter.

Regarding the notebooks themselves, I am much more inclined to move the notebooks to their own repo with different administrators than to add CI testing for them here. Also, I'm am very, very, very reluctant to add dependencies on small projects such as RunNotebook. Have you used nbconverts --to-rst flag? I have not, but that seems like the place to start.

[dacoex]

It sounds like what you really want is something along the lines

Yes.
Do you agree with the idea of porting to rst & doctest?

I would then go ahead with this by the following activities:

• agree on a preliminary structure on how existing tutorials will be included in the ToC: see index.rst & usage.rst
• porting

Whether or not it makes it into version 0.3 (not 3) is another matter.

OK.

Regarding the notebooks themselves, I am much more inclined to move the notebooks to their >own repo with different administrators than to add CI testing for them here.

What a bout the following structure:

1. Essential tuturials that demonstrate the functionality of the package will be ported to rst
2. More application specific tutorials will be moved to the separate repo

I would include all existing notebooks and #84 in item 1 above.

Number 2 could be notebooks that :

• show the use of a specific data set
• demonstrate applications for a specific location or technology
• relate to a specific article / publication
• explain a complete application of a modelchain

Another question about documentation:

• To which extend shall modelchains be documented?
• To which exentd do we want to include cross-comparison with other software?

Looking forward on your feedback.

[wholmgren]

We really need people that are less familiar with pvlib and/or python to give their feedback on the documentation issues. What is working and what is not working?

There are a few different kinds of tutorials, so here are my thoughts on each:

1. Module tutorials (irradiance, atmosphere, clearsky, etc.). I don't think that these module notebooks are very helpful, but maybe others have a different experience. I wrote them as I was learning how to use pvlib, fixing bugs, and adding new features. I think it's the sort of thing where it's useful if you write it, but less useful if you read it. I added them because we were not using rtd at the time (though there was some rst documentation). A lot of the content in these notebooks should go to an examples section for each function, as discussed in Add examples to docstrings #62. We'll probably need a separate page for each function. There will probably also be a few standalone pages that come out of this, though I don't know what yet.
2. Process/application tutorials (tmy_to_power, maybe something like Issue 84: Created a tutorial with system losses and multiple strings. #88). These notebooks make use of many parts of the library. I think a notebook format is ok here, but it would be nice to have an rst format too.
3. Algorithm tutorials (singleaxis, maybe more in the future). I wrote this document as I was porting the single axis tracker code from matlab to python. I think that it might help people understand the algorithm, but it's not relevant to using pvlib. Maybe it's like the supplementary material for a paper. I'd probably leave it alone for now.

To which extend shall modelchains be documented?

Hard to say given that they're so new. I'd start with some discussion about the extensibility of the feature and how it can help with reproducibility. Each subclass would then need to discuss its specific reason for existence, how it works, what the options are, etc.

To which exentd do we want to include cross-comparison with other software?

This is a topic for another issue, but I will say here that I am much more interested in a "Why you should use pvlib" page than a "why you should not use this other software" page.

[dacoex]

@wholmgren thanks for the comments.

I will not work on this further until we agree on how it should be done.
Just doing random PRs without the possibility to merge does not help anyone.
I mean beyond bug fixing, improving docs and adding tests -- such minor items.

Nevertheless, I personally would include rst docs for item 1 and 2 above.

I would suggest to provide a code linked like in the matplotlib gallery.

Looking forward to your response.

[wholmgren]

I don't understand. Are we in disagreement? It sounds like there is plenty of agreement upon which to get started. And it doesn't all have to happen in one PR.

Just doing random PRs without the possibility to merge does not help anyone.

This is not true. Sharing code through PRs is a great way to make an abstract discussion more concrete using a more precise common language (Python instead of English). This is how #88 and #93 both started. #93 will be merged, but as the original comment makes clear, simply sharing code was the original intent. #88 has generated a lot of discussion, and it could be merged if someone edited it.

[dacoex]

Sorry for the strong term when using "disagreement". I perceived the first response as somehow vague.

I just think that there is a difference between code and docs. Docs could be written straight if the structure (ToC) is clear.
That's what I referred to and what where we need to agree on.

Sure, more docstrings with examples are an option for specific use help.

[wholmgren]

Ok, let's try a different approach.

I like the xarray documentation for the following reasons:

1. Short intro page
2. Has a memorable logo
3. I like the presence of "Overview: Why xarray?"
4. A separate installation page that covers optional dependencies.
5. Most of the topic pages have clear names.
6. API reference
7. FAQ
8. What's new

How do you feel about doing something similar to this for pvlib? What would the titles be?

[dacoex]

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

It is structured from the above example xarray:

• [ x] Short intro page
• [ ] Has a memorable logo
• [ x] I like the presence of "Overview: Why xarray?"
• [ x] A separate installation page that covers optional dependencies.
• [ x] Most of the topic pages have clear names.
• [x ] API reference
• [ x] FAQ
• [ x] What's new

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

For the logo I have some ideas but dono how to polish them. Which software would you use to draw it? Inkscape?

[dacoex]

This implementation seems to be also a good example for our case:
http://www.statsmodels.org/dev/examples/index.html

[dacoex]

note to self:
upgrade also to latest api, see #267