Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs have two sets of equivalent notebooks #136

Open
kandersolar opened this issue Feb 21, 2022 · 6 comments
Open

Docs have two sets of equivalent notebooks #136

kandersolar opened this issue Feb 21, 2022 · 6 comments

Comments

@kandersolar
Copy link
Contributor

It seems like there are two sets of equivalent notebooks:

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?

@anomam
Copy link
Contributor

anomam commented Feb 24, 2022

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

@kandersolar
Copy link
Contributor Author

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.

@campanelli-sunpower
Copy link
Contributor

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 :).

@kandersolar
Copy link
Contributor Author

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
Copy link
Contributor

@anomam Did you happen to set up the existing pages build and deployment action?

@anomam
Copy link
Contributor

anomam commented Feb 27, 2022

@campanelli-sunpower wow that looks like a Github bot thingy, first time I see this...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants