Use pydata theme and reorganize pages for sphinx docs #1173

kandersolar · 2021-02-21T17:24:45Z

Maybe addresses define/improve documentation structure #329
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.

useful links:

Built docs here: https://pvlib-python--1173.org.readthedocs.build/en/1173/

List of known issues (feel free to add items here):

No "version switcher" widget (Add version dropdown (for other versions of the docs) pydata/pydata-sphinx-theme#23 and Unidata/MetPy@fc8496d). may be added to the theme soon though: ✨ ENH: Support version and locale switcher pydata/pydata-sphinx-theme#360 RTD adds its own, so no need to wait til the theme has a native widget
~~No "view on github" links in API ref pages~~ fixed

cwhanse · 2021-02-22T16:00:02Z

I like the theme change, in particular the search results are much easier to scan through.

mikofski · 2021-02-22T22:40:41Z

Overall I like the proposed new theme. A better use of space, and good division of the subsections into different navigation areas (left, top, and right)

The biggest change I see is that in the pydata theme the content has been split into subsections in a nav menu at the top, and the subsections within a page are on the right side in a new nav bar, instead of in a tree on the left side:

Instead of the breadcrumbs which weren't really working for us anyway b/c most of our current sections are contained in a single page:

only the example gallery and API have subsections:

mikofski · 2021-02-22T22:46:41Z

I think we should test this with users in the google group or consider sending out a survey. Probably most users won't check GitHub for PSA's, so we have to go after them.

AdamRJensen · 2021-06-14T01:29:20Z

@kanderso-nrel This great and is a very good improvement to the current design. One comment though, on the landing page there is nothing on the left hand side which seems like a waste.

kandersolar · 2021-09-24T19:29:21Z

I think I'm pretty happy with the current state of this PR, with the exception of the landing pages of the User Guide and API Reference which are a little clunky. Open to suggestions there, or OK with me to leave as-is for now and address content changes in a later PR.

I like @mikofski's idea of soliciting feedback from the google group. Happy to push updates if anyone here has feedback, otherwise I'll plan to post there sometime next week.

cwhanse · 2021-09-24T21:41:04Z

I'm in favor of this new style. Are the ads (left side) a "feature" of using this style on readthedocs?

I agree with @mikofski we should canvas users about their preference for docstyle.

kandersolar · 2021-09-24T22:02:37Z

Are the ads (left side) a "feature" of using this style on readthedocs?

With ad blocking disabled I get ads on both this PR build (pydata sphinx theme) and our official docs (readthedocs sphinx theme). Do you see a difference in ads between the new theme and the old? I think a difference would be unexpected.

It is possible to disable ads in the new theme (link). I think I'd lean towards supporting RTD and leaving them in.

Peque · 2021-09-30T07:34:24Z

I like the change as well. 😊

kandersolar · 2021-12-06T22:38:28Z

Maybe the time has come to decide if we will move forward with this PR. Unfortunately the google group thread didn't get much feedback. @adriesse was the only one to reply there (thanks Anton!) and commented on difficulty navigating and locating content. Is it a content organization issue (e.g. grouping many current sidebar pages into a "User Guide"), or is the theme standing in the way of locating things?

I was a little disheartened that there was not more feedback on the google group post. Maybe something like a google form would have been more successful? I imagine some people may have been hesitant to post their thoughts publicly, and in particular in a way that pings a bunch of people. Dear reader, if that applies to you, I promise we think your opinion is interesting -- please share!

cwhanse · 2021-12-06T23:03:52Z

I'm still in favor of the pydata style. It may not fix all frustrations with the current docs but I think it would be an improvement.

mikofski · 2021-12-06T23:53:26Z

do it. Always nice to redecorate. And if we don't like it, we can change it again.

interesting theory around anonymous survey versus open forum discussion. You may be on to something. I have been thinking that we should be doing more surveys.

wholmgren · 2021-12-07T01:14:27Z

+1 for survey (edited to add: don't interpret this as a requirement for this PR, but rather that I am in favor of using surveys for things like this in the future)

adriesse · 2021-12-07T10:15:21Z

Just because I was the only who commented, that doesn't mean my opinion deserves more weight. Go ahead, make the change!

Anyway, I just had another look at before and after, and for pvlib I do find this to be an improvement.

mikofski

I think this is a vast improvement. I like how it uses space well and organizes both chapters (horizontally as bread crumbs on top) and page sections (vertically along the left) and addition has links to jump to all of our most important external links like the google group, SO[pvlib], and PyPI. Thanks @kanderso-nrel !

mikofski · 2021-12-07T19:31:10Z

@wholmgren & @cwhanse are you okay with merging this? Any objections from anyone? Let's timebox this and say we'll close this issue either way by Friday, okay? no pressure 🤣 j/k whenever seriously no pressure

wholmgren

Ok with me to merge.

Is there a reason the What's New and the Contributing subsections are on the right side while the left is empty? I guess I expected subsections on the left and subsubsections on the right.

kandersolar · 2021-12-07T20:10:37Z

Is there a reason the What's New and the Contributing subsections are on the right side while the left is empty? I guess I expected subsections on the left and subsubsections on the right.

I think the logic is that sub-pages go on the left and in-page hierarchy goes on the right. Whatsnew and Contributing are all on one page (so no subpages -> no left sidebar), while e.g. the Gallery and API Reference have sub-pages.

wholmgren · 2021-12-07T20:12:58Z

Ah, separately I had been thinking we should break the whats new into subpages but doesn't have to be done here.

mikofski · 2021-12-07T21:28:50Z

🚀

* fix heading levels in user_guide/bifacial.rst * whatsnew cleanup * fix readme html missing tag, maybe unicode zero-width spaces? * readme: link to universal zenodo doi * readme: update installation link for #1173 * whatsnew date * additional contributors * delete errant space

commit 5047b26 Author: Prajwal Borkar <[email protected]> Date: Tue May 17 19:14:53 2022 +0530 Updated get_cams protocol to https pvlib#1457 (pvlib#1458) * Updated get_cams protocol to https pvlib#1457 * Updated instances of http to https. pvlib#1457 * Updated documentation links to https * Added Contributor commit a0812b1 Author: roger-lcc <[email protected]> Date: Wed May 4 20:01:42 2022 +0800 CI asv check (pvlib#1454) * CI asv check * added CI asv check * CI asv check * CI asv check * updated CI asv check * Update docs/sphinx/source/whatsnew/v0.9.2.rst updated v0.9.2.rst Co-authored-by: Kevin Anderson <[email protected]> Co-authored-by: Kevin Anderson <[email protected]> commit 83e379a Author: Kevin Anderson <[email protected]> Date: Thu Apr 28 19:26:09 2022 -0400 Bump pandas to 0.25.0; test updates (pvlib#1448) * bump pandas min from 0.22.0 to 0.25.0 * fix buggy test__check_pandas_assert_kwargs don't use monkeypatch and mocker in the same test function. pytest-dev/pytest-mock#289 * fix psm3 test (apparent_zenith -> solar_zenith) * whatsnew * better UTC conversion in sun_rise_set_transit_ephem * helpful comments * more whatsnew * '3.0' -> '3' in read_crn test? * apply dtypes during parsing in read_crn * move dropna() post-processing into read_fwf call * fix read_crn for pandas<1.2.0 * Update pvlib/solarposition.py Co-authored-by: Will Holmgren <[email protected]> * nix pytz * UTC -> utc * address simd arccos issue in tracking.singleaxis Co-authored-by: Will Holmgren <[email protected]> commit 8d0f863 Author: Naman Priyadarshi <[email protected]> Date: Tue Apr 12 22:55:58 2022 +0530 Advance numba from 0.36.1 to 0.40.0 in asv py3.6 environment (pvlib#1440) * Advance numba from 0.36.1 to 0.40.0 * Advance numba from 0.36.1 to 0.40.0 * Updated whatsnew.rst commit 5cb695d Author: Naman Priyadarshi <[email protected]> Date: Wed Apr 6 23:58:03 2022 +0530 Remove unnecessary **kwargs from spa_python and get_total_irradiance (pvlib#1437) * Update Solarposition.py Removed **kwargs from pvlib.solarposition.spa_python * Added v0.9.2.rst, changes in pvlib/irradiance.py and pvlib/location.py Made new v0.9.2.rst and removed **kwargs from pvlib/irradiance.py (Line 309) and pvlib/location.py (Line 234-235) * Update docs/sphinx/source/whatsnew/v0.9.2.rst * Update docs/sphinx/source/whatsnew/v0.9.2.rst Co-authored-by: Kevin Anderson <[email protected]> commit 8460b36 Author: Kevin Anderson <[email protected]> Date: Tue Mar 29 15:31:25 2022 -0600 Finalize 0.9.1 (pvlib#1431) * fix heading levels in user_guide/bifacial.rst * whatsnew cleanup * fix readme html missing tag, maybe unicode zero-width spaces? * readme: link to universal zenodo doi * readme: update installation link for pvlib#1173 * whatsnew date * additional contributors * delete errant space commit edbf2a6 Author: RoyCoding8 <[email protected]> Date: Wed Mar 30 01:58:18 2022 +0530 Updated plot_singlediode.py (pvlib#1434) * Update plot_singlediode.py Changed the unit from C to degree C (°C) * Update plot_singlediode.py Changed to LaTeX \degree symbol in matplotlib which avoids any encoding issues with using Unicode characters. * Update v0.9.1.rst Added name to the contributors' list * Update v0.9.1.rst commit cf4a8ad Author: Kevin Anderson <[email protected]> Date: Tue Mar 29 14:04:40 2022 -0600 Update sphinx to 4.5.0 (pvlib#1435) * bump sphinx and pydata-sphinx-theme versions * clean up sphinx conf.py * fix distutils strangeness, maybe * use freshly-released sphinx==4.5.0 commit 884a153 Author: Kevin Anderson <[email protected]> Date: Wed Mar 23 13:41:35 2022 -0600 Clarify delta_t docstring descriptions (pvlib#1429) * clarify delta_t docstrings * whatsnew commit c243183 Author: Kevin Anderson <[email protected]> Date: Thu Mar 17 12:01:57 2022 -0600 Deprecate pvlib.forecast (pvlib#1426) * deprecate pvlib.forecast classes * catch warnings in tests * add warning admonition to forecasts.rst * whatsnew * stickler * pin pytest < 7.1.0 * pin pytest in the right place this time * more warning suppression in tests * unpin pytest * Update docs/sphinx/source/whatsnew/v0.9.1.rst * copy warning to reference/forecasting.rst commit e3baa12 Author: Kevin Anderson <[email protected]> Date: Thu Mar 17 11:28:56 2022 -0600 Fix conditional dependency on dataclasses (pvlib#1422) * better conditional dependency on dataclasses * whatsnew commit 27cba7a Author: Naman Priyadarshi <[email protected]> Date: Thu Mar 17 22:48:08 2022 +0530 Added asv benchmarking badge to the table of badges in the main README. (pvlib#1427) * Update Readme.md Added benchmarks asv badge to the badge section * Updated v.0.9.1.rst Added my name to the list of Contributers. commit 1893b20 Author: Adam R. Jensen <[email protected]> Date: Mon Mar 14 18:37:58 2022 +0100 Add variable mapping of psm3 (pvlib#1374) * Add variable mapping of psm3 * Add enhancement entry in whatsnew * Fix stickler * Map keys in metadata dict * Remove double spaces in docs * Fix stickler * Doc update Co-authored-by: Kevin Anderson <[email protected]> * Reformatting - changes by kanderso-nrel * Update docstring table with 2020 * Add deprecation warning test coverage * Rename to VARIABLE_MAP * Change apparent_zenith to solar_zenith Based on the decision in pvlib#1403 * Update attributes docstring * Change elevation to altitude when mapping variables * Update psm3 variable mapping test Co-authored-by: Kevin Anderson <[email protected]>

* Add cams.get_cams_radiation function * Revert "Add cams.get_cams_radiation function" This reverts commit d7deb80. * Allow parsing of http files * Add test for https file * Squashed commit of the following: commit 5047b26 Author: Prajwal Borkar <[email protected]> Date: Tue May 17 19:14:53 2022 +0530 Updated get_cams protocol to https #1457 (#1458) * Updated get_cams protocol to https #1457 * Updated instances of http to https. #1457 * Updated documentation links to https * Added Contributor commit a0812b1 Author: roger-lcc <[email protected]> Date: Wed May 4 20:01:42 2022 +0800 CI asv check (#1454) * CI asv check * added CI asv check * CI asv check * CI asv check * updated CI asv check * Update docs/sphinx/source/whatsnew/v0.9.2.rst updated v0.9.2.rst Co-authored-by: Kevin Anderson <[email protected]> Co-authored-by: Kevin Anderson <[email protected]> commit 83e379a Author: Kevin Anderson <[email protected]> Date: Thu Apr 28 19:26:09 2022 -0400 Bump pandas to 0.25.0; test updates (#1448) * bump pandas min from 0.22.0 to 0.25.0 * fix buggy test__check_pandas_assert_kwargs don't use monkeypatch and mocker in the same test function. pytest-dev/pytest-mock#289 * fix psm3 test (apparent_zenith -> solar_zenith) * whatsnew * better UTC conversion in sun_rise_set_transit_ephem * helpful comments * more whatsnew * '3.0' -> '3' in read_crn test? * apply dtypes during parsing in read_crn * move dropna() post-processing into read_fwf call * fix read_crn for pandas<1.2.0 * Update pvlib/solarposition.py Co-authored-by: Will Holmgren <[email protected]> * nix pytz * UTC -> utc * address simd arccos issue in tracking.singleaxis Co-authored-by: Will Holmgren <[email protected]> commit 8d0f863 Author: Naman Priyadarshi <[email protected]> Date: Tue Apr 12 22:55:58 2022 +0530 Advance numba from 0.36.1 to 0.40.0 in asv py3.6 environment (#1440) * Advance numba from 0.36.1 to 0.40.0 * Advance numba from 0.36.1 to 0.40.0 * Updated whatsnew.rst commit 5cb695d Author: Naman Priyadarshi <[email protected]> Date: Wed Apr 6 23:58:03 2022 +0530 Remove unnecessary **kwargs from spa_python and get_total_irradiance (#1437) * Update Solarposition.py Removed **kwargs from pvlib.solarposition.spa_python * Added v0.9.2.rst, changes in pvlib/irradiance.py and pvlib/location.py Made new v0.9.2.rst and removed **kwargs from pvlib/irradiance.py (Line 309) and pvlib/location.py (Line 234-235) * Update docs/sphinx/source/whatsnew/v0.9.2.rst * Update docs/sphinx/source/whatsnew/v0.9.2.rst Co-authored-by: Kevin Anderson <[email protected]> commit 8460b36 Author: Kevin Anderson <[email protected]> Date: Tue Mar 29 15:31:25 2022 -0600 Finalize 0.9.1 (#1431) * fix heading levels in user_guide/bifacial.rst * whatsnew cleanup * fix readme html missing tag, maybe unicode zero-width spaces? * readme: link to universal zenodo doi * readme: update installation link for #1173 * whatsnew date * additional contributors * delete errant space commit edbf2a6 Author: RoyCoding8 <[email protected]> Date: Wed Mar 30 01:58:18 2022 +0530 Updated plot_singlediode.py (#1434) * Update plot_singlediode.py Changed the unit from C to degree C (°C) * Update plot_singlediode.py Changed to LaTeX \degree symbol in matplotlib which avoids any encoding issues with using Unicode characters. * Update v0.9.1.rst Added name to the contributors' list * Update v0.9.1.rst commit cf4a8ad Author: Kevin Anderson <[email protected]> Date: Tue Mar 29 14:04:40 2022 -0600 Update sphinx to 4.5.0 (#1435) * bump sphinx and pydata-sphinx-theme versions * clean up sphinx conf.py * fix distutils strangeness, maybe * use freshly-released sphinx==4.5.0 commit 884a153 Author: Kevin Anderson <[email protected]> Date: Wed Mar 23 13:41:35 2022 -0600 Clarify delta_t docstring descriptions (#1429) * clarify delta_t docstrings * whatsnew commit c243183 Author: Kevin Anderson <[email protected]> Date: Thu Mar 17 12:01:57 2022 -0600 Deprecate pvlib.forecast (#1426) * deprecate pvlib.forecast classes * catch warnings in tests * add warning admonition to forecasts.rst * whatsnew * stickler * pin pytest < 7.1.0 * pin pytest in the right place this time * more warning suppression in tests * unpin pytest * Update docs/sphinx/source/whatsnew/v0.9.1.rst * copy warning to reference/forecasting.rst commit e3baa12 Author: Kevin Anderson <[email protected]> Date: Thu Mar 17 11:28:56 2022 -0600 Fix conditional dependency on dataclasses (#1422) * better conditional dependency on dataclasses * whatsnew commit 27cba7a Author: Naman Priyadarshi <[email protected]> Date: Thu Mar 17 22:48:08 2022 +0530 Added asv benchmarking badge to the table of badges in the main README. (#1427) * Update Readme.md Added benchmarks asv badge to the badge section * Updated v.0.9.1.rst Added my name to the list of Contributers. commit 1893b20 Author: Adam R. Jensen <[email protected]> Date: Mon Mar 14 18:37:58 2022 +0100 Add variable mapping of psm3 (#1374) * Add variable mapping of psm3 * Add enhancement entry in whatsnew * Fix stickler * Map keys in metadata dict * Remove double spaces in docs * Fix stickler * Doc update Co-authored-by: Kevin Anderson <[email protected]> * Reformatting - changes by kanderso-nrel * Update docstring table with 2020 * Add deprecation warning test coverage * Rename to VARIABLE_MAP * Change apparent_zenith to solar_zenith Based on the decision in #1403 * Update attributes docstring * Change elevation to altitude when mapping variables * Update psm3 variable mapping test Co-authored-by: Kevin Anderson <[email protected]> * Revert "Squashed commit of the following:" This reverts commit b313c64. * Update whatsnew * Update read_surfrad documentation Co-authored-by: AdamRJensen <[email protected]>

proof of concept

e052c8f

kandersolar added 2 commits April 15, 2021 17:58

Merge branch 'master' into pydata_theme

81cad8b

stickler

9d7ac49

kandersolar added 13 commits June 29, 2021 13:38

Merge remote-tracking branch 'upstream/master' into pydata_theme

b6c14d2

fix "view on github" links

15a541f

misc edits

f794fef

Merge remote-tracking branch 'upstream/master' into pydata_theme

eea2b8b

Merge remote-tracking branch 'upstream/master' into pydata_theme

0546f6f

stickler

37a7145

add favicons (!)

8a9a7e3

header icons for stackoverflow, google group, pypi

72bc21d

clean up left sidebar by breaking out api sections into separate files

d1309ae

rename auto_examples -> gallery

6af9b28

update gitignore

8c5430a

merge master

fa35149

kandersolar marked this pull request as ready for review September 24, 2021 19:22

kandersolar added the documentation label Sep 24, 2021

kandersolar added this to the 0.9.1 milestone Sep 24, 2021

kandersolar changed the title ~~[WIP] Use pydata theme and reorganize pages for sphinx docs~~ Use pydata theme and reorganize pages for sphinx docs Sep 24, 2021

mikofski approved these changes Dec 7, 2021

View reviewed changes

wholmgren approved these changes Dec 7, 2021

View reviewed changes

mikofski merged commit db7e5d8 into pvlib:master Dec 7, 2021

kandersolar deleted the pydata_theme branch December 7, 2021 21:30

kandersolar mentioned this pull request Dec 8, 2021

Add version warning banner for "latest" sphinx docs #1346

Merged

4 tasks

AdamRJensen mentioned this pull request Dec 16, 2021

Change advertisement position in new pydata theme #1358

Closed

kandersolar mentioned this pull request Dec 29, 2021

Broken link in read_midc documentation #1363

Closed

kandersolar mentioned this pull request Mar 2, 2022

Forecasting page in User's guide #1417

Closed

kandersolar added a commit to kandersolar/pvlib-python that referenced this pull request Mar 23, 2022

readme: update installation link for pvlib#1173

7897dc9

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Use pydata theme and reorganize pages for sphinx docs #1173

Use pydata theme and reorganize pages for sphinx docs #1173

kandersolar commented Feb 21, 2021 •

edited

Loading

cwhanse commented Feb 22, 2021

mikofski commented Feb 22, 2021 •

edited

Loading

mikofski commented Feb 22, 2021

AdamRJensen commented Jun 14, 2021

kandersolar commented Sep 24, 2021

cwhanse commented Sep 24, 2021

kandersolar commented Sep 24, 2021

Peque commented Sep 30, 2021

kandersolar commented Dec 6, 2021

cwhanse commented Dec 6, 2021

mikofski commented Dec 6, 2021

wholmgren commented Dec 7, 2021 •

edited

Loading

adriesse commented Dec 7, 2021 •

edited

Loading

mikofski left a comment

mikofski commented Dec 7, 2021 •

edited

Loading

wholmgren left a comment

kandersolar commented Dec 7, 2021

wholmgren commented Dec 7, 2021

mikofski commented Dec 7, 2021

Use pydata theme and reorganize pages for sphinx docs #1173

Use pydata theme and reorganize pages for sphinx docs #1173

Conversation

kandersolar commented Feb 21, 2021 • edited Loading

cwhanse commented Feb 22, 2021

mikofski commented Feb 22, 2021 • edited Loading

mikofski commented Feb 22, 2021

AdamRJensen commented Jun 14, 2021

kandersolar commented Sep 24, 2021

cwhanse commented Sep 24, 2021

kandersolar commented Sep 24, 2021

Peque commented Sep 30, 2021

kandersolar commented Dec 6, 2021

cwhanse commented Dec 6, 2021

mikofski commented Dec 6, 2021

wholmgren commented Dec 7, 2021 • edited Loading

adriesse commented Dec 7, 2021 • edited Loading

mikofski left a comment

Choose a reason for hiding this comment

mikofski commented Dec 7, 2021 • edited Loading

wholmgren left a comment

Choose a reason for hiding this comment

kandersolar commented Dec 7, 2021

wholmgren commented Dec 7, 2021

mikofski commented Dec 7, 2021

kandersolar commented Feb 21, 2021 •

edited

Loading

mikofski commented Feb 22, 2021 •

edited

Loading

wholmgren commented Dec 7, 2021 •

edited

Loading

adriesse commented Dec 7, 2021 •

edited

Loading

mikofski commented Dec 7, 2021 •

edited

Loading