bifacial_radiance icon indicating copy to clipboard operation
bifacial_radiance copied to clipboard

Switch to pydata-sphinx-theme; reorganize docs pages into user guide; add example gallery

Open kandersolar opened this issue 1 year ago • 1 comments

At the suggestion of @shirubana, here is a PR that does several things:

  1. 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.
  2. 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.
  3. 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.

kandersolar avatar Sep 01 '22 21:09 kandersolar

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 because nbsphinx 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.

kandersolar avatar Sep 01 '22 22:09 kandersolar