SunPower
Docs have two sets of equivalent notebooks
It seems like there are two sets of equivalent notebooks:
- https://github.com/SunPower/pvfactors/tree/master/docs/tutorials
- https://github.com/SunPower/pvfactors/tree/master/docs/sphinx/tutorials
On first glance it seems like the notebook contents are identical, with the exception of pvfactors_demo.ipynb which is only in docs/tutorials. What's the motivation to have two sets of notebooks?
Oh right, I think at the time I wanted to store the tutorials outside of the sphinx folder, but I couldn't find a way to have sphinx build the docs with the notebook if it wasn't in it... but that's definitely not great 😅 I think it's just fine if we put a link to the sphinx/tutorials folder in the README and docs
Oh I see, that makes sense. We had the same dilemma with rdtools and solved it using nbsphinx-link. It works by putting small shim files in a place that sphinx can find but they point to the outside-of-sphinx location where the real notebooks are. Here's an example: https://github.com/NREL/rdtools/blob/master/docs/sphinx/source/examples/degradation_and_soiling_example_pvdaq_4.nblink
It has always felt brittle to me though and I think I'd lean towards your suggestion of just having the notebooks live in sphinx/tutorials.
FWIW: I think I saw this issue when I generated the v1.5.2 docs and had extra copies of the notebooks floating around in the gh-pages branch that I removed before pushing. It'd be nice if this process were harder to screw up :).
I'm a big fan of automated jobs that deploy docs, upload distributions to PyPI, etc on new releases. It's pretty easy to set up that kind of thing with GitHub Actions nowadays, see https://github.com/pvlib/pvlib-python/blob/master/.github/workflows/publish.yml
@campanelli-sunpower wow that looks like a Github bot thingy, first time I see this...