bifacial_radiance
bifacial_radiance copied to clipboard
Switch to pydata-sphinx-theme; reorganize docs pages into user guide; add example gallery
At the suggestion of @shirubana, here is a PR that does several things:
- Switches from the readthedocs sphinx theme to the pydata sphinx theme (what pvlib currently uses). Subjectively I think it looks better, but it also has a bit of a nicer navigation/organization where major website sections are at the top with subsections along the side.
- With the ability to use the new theme's new top-level organization, several of the pages are demoted to sub-sections in a new "user guide" section.
- Adds an example gallery page like those of pvlib and rdtools. These are built from the jupyter notebook files, meaning they are not executed during the docs build, just translated to HTML, and so the burden is on the maintainers to make sure they are kept up to date.
I think Silvana just enabled RTD PR builds, so hopefully we'll get to see what this looks like in the CI status checks.
Ok, check it out: https://bifacial-radiance--432.org.readthedocs.build/en/432/index.html
Here are some TODOs that I think yall are better equipped to deal with than I am:
- See here for how to set thumbnails for the gallery: https://nbsphinx.readthedocs.io/en/0.8.9/subdir/gallery.html
- If you look at a RTD build log you will see many warnings like
CRITICAL: Title level inconsistent:
, and the notebooks are rendered strangely sometimes. This is becausenbsphinx
wants the title depth to only go down by one, e.g.# Big title
only followed by## Medium title
, not### Little title
. So someone should go through the notebooks and make the titles only go down by one at a time. - May want to rename the notebooks to have shorter titles; some of them get a little cut off in the gallery page because they are so long.
Anyway let me know if you want me to make any more changes. I don't plan to do anything else here unless prompted.