Create make.bat for building sphinx docs on Windows

[kandersolar]

• Closes Make building docs on windows slightly easier #978
• I am familiar with the contributing guidelines
• Tests added
• Updates entries to docs/sphinx/source/api.rst for API changes.
• Adds description and name entries in the appropriate "what's new" file in docs/sphinx/source/whatsnew for all changes. Includes link to the GitHub Issue with :issue:`num` or this Pull Request with :pull:`num`. Includes contributor name and/or GitHub username (link with :ghuser:`user`).
• New code is fully documented. Includes numpydoc compliant docstrings, examples, and comments where necessary.
• Pull request is nearly complete and ready for detailed review.
• Maintainer: Appropriate GitHub Labels and Milestone are assigned to the Pull Request and linked Issue.

This is the stock script from Sphinx. Works on my Windows test machine, would be good if someone else could verify it works for them as well.

In case this will help someone searching in the future: building the docs on Windows with ipython 7.8.0 caused lots of warnings like WARNING: image file not readable: savefiglocation-basic.png. It appears to be some issue with backslashes in filepaths (note the lack of separation between savefig and location-basic.png). Didn't see any warnings on Linux with the same ipython version. Upgrading to 7.15.0 fixed it.

I also noticed this warning: source/whatsnew/v0.3.0.txt:51: WARNING: undefined label: api (if the link has no caption the label must precede a section header). Here's the link it's talking about: https://pvlib-python.readthedocs.io/en/stable/whatsnew.html#id85, (Moved to API reference in GH258)

Apparently it links out to the pandas docs now and I only noticed it from a transient network quirk that caused the pandas intersphinx inventory to not load when I was building the docs. Probably not a big deal, but thought I'd mention it.

[wholmgren]

@mikofski or @cwhanse can you confirm the make.bat works as expected?

[cwhanse]

It runs for me but raises a bunch of warnings, and the dependency install had a speedbump.

I didn't have the sphinx_rtd_them and nbsphinx dependencies. pip install pvlib[doc] took care of those two but could not update docutils from 0.14, since that was installed via distutils with the Anaconda3 distribution. Couldn't pip install --upgrade docutils separately. I had to conda install docutils=0.15.2

There are a bunch of warnings of this nature:

c:\python\pvlib-python\pvlib-python\docs\sphinx\source\clearsky.rst:: WARNING: image file not readable: savefiglocation-basic.png

When I look at the generated files

• clearsky.html
• forecasts.html
• package_overview.html
• timetimezones.html (odd file name)

there are broken links to the missing figures. Not sure what I should look for to see why the figures are missing.

When processing clearsky there are two instances of this warning:

WARNING:matplotlib.legend:No handles with labels found to put in legend.

[kandersolar]

Thanks for trying it out @cwhanse.

pip install pvlib[doc] took care of those two but could not update docutils from 0.14, since that was installed via distutils with the Anaconda3 distribution. Couldn't pip install --upgrade docutils separately. I had to conda install docutils=0.15.2

Not sure if there's a good way to avoid that. I think we do want a newer version of docutils than 0.14. Maybe worth a note in #982?

c:\python\pvlib-python\pvlib-python\docs\sphinx\source\clearsky.rst:: WARNING: image file not readable: savefiglocation-basic.png

I saw similar issues -- see the note in the original post, but it was fixed by upgrading ipython to 7.15.0. Maybe we should restrict the ipython versions we allow in EXTRAS_REQUIRE.

WARNING:matplotlib.legend:No handles with labels found to put in legend.

Not sure about this one. I don't see it in my builds.

[cwhanse]

Maybe worth a note in #982?

Yes

c:\python\pvlib-python\pvlib-python\docs\sphinx\source\clearsky.rst:: WARNING: image file not readable: savefiglocation-basic.png

I saw similar issues -- see the note in the original post, but it was fixed by upgrading ipython to 7.15.0. Maybe we should restrict the ipython versions we allow in EXTRAS_REQUIRE.

With ipython=7.15.0 (I was on 6.X.X) make.bat doesn't run, there's an error generated from clearsky.rst

Exception occurred:
File "c:\users\cliff\anaconda3\lib\site-packages\IPython\sphinxext\ipython_directive.py", line 586, in process_input
raise RuntimeError('Non Expected warning in {} line {}'.format(filename, lineno))
RuntimeError: Non Expected warning in c:\python\pvlib-python\pvlib-python\docs\sphinx\source\clearsky.rst line 54
The full traceback has been saved in C:\Users\cliff\AppData\Local\Temp\sphinx-err-u9tbpr_k.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at https://github.com/sphinx-doc/sphinx/issues. Thanks!

Since clearsky.rst hasn't changed, must be a difference between your configuration and mine. Any ideas?

[kandersolar]

Any ideas?

Not really. If you post a pip freeze then I can recreate that environment and try to figure out what's going on.

[cwhanse]

python 3.6.4

Emailed you the freeze file.

[cwhanse]

From a clean py3.6 environment, the make file almost runs to completion with the following dependencies: sphinx, sphinx_rtd_theme, nbsphinx, ipython and pillow. sphinx hangs and complains about the re-use of sapm2 as an equation label in two functions in pvlib.temperature, perhaps that can be fixed in this PR.

[kandersolar]

I've sometimes have builds hang on windows that pick up again like nothing happened when I hit enter a few times to "wake it up". No clue why, but I'm inclined to blame the windows command prompt.

with the following dependencies: sphinx, sphinx_rtd_theme, nbsphinx, ipython and pillow

Is nbsphinx a requirement? I don't have it in the environment I use to build the pvlib docs.

[wholmgren]

Is nbsphinx a requirement?

No, but it used to be.

Seems like the build problems are not directly related to adding the make.bat file so we should go ahead and merge this (once the conflict is resolved). Ok?

[cwhanse]

thanks @kanderso-nrel