Use pydata theme and reorganize pages for sphinx docs (#1173)

* proof of concept

* stickler

* fix "view on github" links

* misc edits

* stickler

* add favicons (!)

* header icons for stackoverflow, google group, pypi

* bump copyright year to 2021

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

* rename auto_examples -> gallery

* update gitignore

Author: kandersolar

.gitignore

@@ -39,9 +39,9 @@ pvlib/spa_c_files/spa.h
 pvlib/spa_c_files/spa_tester.c
 
 # generated documentation
-docs/sphinx/source/generated
+docs/sphinx/source/reference/generated
 docs/sphinx/source/savefig
-docs/sphinx/source/auto_examples
+docs/sphinx/source/gallery
 
 # Installer logs
 pip-log.txt

docs/sphinx/Makefile

@@ -48,8 +48,8 @@ help:
 
 clean:
 	rm -rf $(BUILDDIR)/*
-	rm -rf source/generated
-	rm -rf source/auto_examples
+	rm -rf source/reference/generated
+	rm -rf source/gallery
 	rm -rf source/savefig
 
 html:

docs/sphinx/make.bat

@@ -17,8 +17,8 @@ if "%1" == "clean" (
     REM override the default `make clean` behavior of sphinx-build;
     REM this lets us clean out the various build files in sphinx/source/
 	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
-	rmdir /q /s %SOURCEDIR%\generated >nul 2>&1
-	rmdir /q /s %SOURCEDIR%\auto_examples >nul 2>&1
+	rmdir /q /s %SOURCEDIR%\reference\generated >nul 2>&1
+	rmdir /q /s %SOURCEDIR%\gallery >nul 2>&1
 	rmdir /q /s %SOURCEDIR%\savefig >nul 2>&1
 	goto end
 )

docs/sphinx/source/_static/favicon-16x16.png

@@ -0,0 +1,19 @@
+{#
+
+Modify the "Edit on Github" links to handle auto-generated pages in the
+example gallery and the API reference listings.  The GH links that sphinx
+generates by default make the assumption that an HTML file comes from an RST
+file with the same filepath, which isn't the case for autogenerated files. The
+logic to generate the correct URL is in conf.py, but we still have to modify
+the template here to change the "Edit this page" text to "View on GitHub".
+
+#}
+
+{% if sourcename is defined and theme_use_edit_page_button==true and page_source_suffix %}
+{% set src = sourcename.split('.') %}
+<div class="tocsection editthispage">
+    <a href="{{ get_edit_url() }}">
+        <i class="fab fa-github-square"></i> {{ _("View on GitHub") }}
+    </a>
+</div>
+{% endif %}