From e052c8f7ff844a9bd14a6f9e7c2bcb0983ebaadc Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Sun, 21 Feb 2021 10:19:03 -0700 Subject: [PATCH 01/11] proof of concept --- docs/sphinx/source/conf.py | 21 ++++++++++--------- docs/sphinx/source/index.rst | 14 ++----------- .../source/{ => user_guide}/clearsky.rst | 0 .../comparison_pvlib_matlab.rst | 0 .../source/{ => user_guide}/forecasts.rst | 0 docs/sphinx/source/user_guide/index.rst | 20 ++++++++++++++++++ .../source/{ => user_guide}/installation.rst | 2 +- .../source/{ => user_guide}/introtutorial.rst | 0 .../source/{ => user_guide}/modelchain.rst | 0 .../{ => user_guide}/package_overview.rst | 0 .../source/{ => user_guide}/pvsystem.rst | 0 .../source/{ => user_guide}/singlediode.rst | 0 .../source/{ => user_guide}/timetimezones.rst | 0 .../variables_style_rules.rst | 2 +- setup.py | 2 +- 15 files changed, 36 insertions(+), 25 deletions(-) rename docs/sphinx/source/{ => user_guide}/clearsky.rst (100%) rename docs/sphinx/source/{ => user_guide}/comparison_pvlib_matlab.rst (100%) rename docs/sphinx/source/{ => user_guide}/forecasts.rst (100%) create mode 100644 docs/sphinx/source/user_guide/index.rst rename docs/sphinx/source/{ => user_guide}/installation.rst (99%) rename docs/sphinx/source/{ => user_guide}/introtutorial.rst (100%) rename docs/sphinx/source/{ => user_guide}/modelchain.rst (100%) rename docs/sphinx/source/{ => user_guide}/package_overview.rst (100%) rename docs/sphinx/source/{ => user_guide}/pvsystem.rst (100%) rename docs/sphinx/source/{ => user_guide}/singlediode.rst (100%) rename docs/sphinx/source/{ => user_guide}/timetimezones.rst (100%) rename docs/sphinx/source/{ => user_guide}/variables_style_rules.rst (96%) diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index f01446e813..a1249bf953 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -127,20 +127,21 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -# on_rtd is whether we are on readthedocs.org -on_rtd = os.environ.get('READTHEDOCS', None) == 'True' - -if not on_rtd: # only import and set the theme if we're building docs locally - import sphinx_rtd_theme - html_theme = 'sphinx_rtd_theme' - html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] -else: - html_theme = 'default' +html_theme = "pydata_sphinx_theme" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -#html_theme_options = {} +html_theme_options = { + #"external_links": [ + # {"url": "https://pandas.pydata.org/pandas-docs/stable/", "name": "Pandas Docs"} + #], + #"github_url": "https://github.com/pandas-dev/pydata-sphinx-theme", + #"twitter_url": "https://twitter.com/pandas_dev", + #"use_edit_page_button": True, + "show_toc_level": 1, + # "navbar_align": "right", # For testing that the navbar items align properly +} # Add any paths that contain custom themes here, relative to this directory. #html_theme_path = [] diff --git a/docs/sphinx/source/index.rst b/docs/sphinx/source/index.rst index 1717ec233f..4a7f282a93 100644 --- a/docs/sphinx/source/index.rst +++ b/docs/sphinx/source/index.rst @@ -90,21 +90,11 @@ Contents .. toctree:: :maxdepth: 1 - package_overview - introtutorial + user_guide/index auto_examples/index + api whatsnew - installation contributing - pvsystem - modelchain - timetimezones - clearsky - forecasts - api - comparison_pvlib_matlab - variables_style_rules - singlediode Indices and tables diff --git a/docs/sphinx/source/clearsky.rst b/docs/sphinx/source/user_guide/clearsky.rst similarity index 100% rename from docs/sphinx/source/clearsky.rst rename to docs/sphinx/source/user_guide/clearsky.rst diff --git a/docs/sphinx/source/comparison_pvlib_matlab.rst b/docs/sphinx/source/user_guide/comparison_pvlib_matlab.rst similarity index 100% rename from docs/sphinx/source/comparison_pvlib_matlab.rst rename to docs/sphinx/source/user_guide/comparison_pvlib_matlab.rst diff --git a/docs/sphinx/source/forecasts.rst b/docs/sphinx/source/user_guide/forecasts.rst similarity index 100% rename from docs/sphinx/source/forecasts.rst rename to docs/sphinx/source/user_guide/forecasts.rst diff --git a/docs/sphinx/source/user_guide/index.rst b/docs/sphinx/source/user_guide/index.rst new file mode 100644 index 0000000000..432b7de7a7 --- /dev/null +++ b/docs/sphinx/source/user_guide/index.rst @@ -0,0 +1,20 @@ +========== +User Guide +========== + + +.. toctree:: + :maxdepth: 2 + :caption: Demo Documentation + + package_overview + installation + introtutorial + pvsystem + modelchain + timetimezones + clearsky + forecasts + comparison_pvlib_matlab + variables_style_rules + singlediode diff --git a/docs/sphinx/source/installation.rst b/docs/sphinx/source/user_guide/installation.rst similarity index 99% rename from docs/sphinx/source/installation.rst rename to docs/sphinx/source/user_guide/installation.rst index 39b7bfc974..cc8fe1c8b9 100644 --- a/docs/sphinx/source/installation.rst +++ b/docs/sphinx/source/user_guide/installation.rst @@ -146,7 +146,7 @@ Follow these steps to obtain the library using git/GitHub: This button is circled in the image below. Remember the system path that you clone the library to. -.. image:: _images/clonebutton.png +.. image:: ../_images/clonebutton.png Please see GitHub's `Forking Projects `_, diff --git a/docs/sphinx/source/introtutorial.rst b/docs/sphinx/source/user_guide/introtutorial.rst similarity index 100% rename from docs/sphinx/source/introtutorial.rst rename to docs/sphinx/source/user_guide/introtutorial.rst diff --git a/docs/sphinx/source/modelchain.rst b/docs/sphinx/source/user_guide/modelchain.rst similarity index 100% rename from docs/sphinx/source/modelchain.rst rename to docs/sphinx/source/user_guide/modelchain.rst diff --git a/docs/sphinx/source/package_overview.rst b/docs/sphinx/source/user_guide/package_overview.rst similarity index 100% rename from docs/sphinx/source/package_overview.rst rename to docs/sphinx/source/user_guide/package_overview.rst diff --git a/docs/sphinx/source/pvsystem.rst b/docs/sphinx/source/user_guide/pvsystem.rst similarity index 100% rename from docs/sphinx/source/pvsystem.rst rename to docs/sphinx/source/user_guide/pvsystem.rst diff --git a/docs/sphinx/source/singlediode.rst b/docs/sphinx/source/user_guide/singlediode.rst similarity index 100% rename from docs/sphinx/source/singlediode.rst rename to docs/sphinx/source/user_guide/singlediode.rst diff --git a/docs/sphinx/source/timetimezones.rst b/docs/sphinx/source/user_guide/timetimezones.rst similarity index 100% rename from docs/sphinx/source/timetimezones.rst rename to docs/sphinx/source/user_guide/timetimezones.rst diff --git a/docs/sphinx/source/variables_style_rules.rst b/docs/sphinx/source/user_guide/variables_style_rules.rst similarity index 96% rename from docs/sphinx/source/variables_style_rules.rst rename to docs/sphinx/source/user_guide/variables_style_rules.rst index 5baf80ec0c..dc826b77bd 100644 --- a/docs/sphinx/source/variables_style_rules.rst +++ b/docs/sphinx/source/user_guide/variables_style_rules.rst @@ -6,7 +6,7 @@ Variables and Symbols There is a convention on consistent variable names throughout the library: .. csv-table:: List of used Variables and Parameters - :file: ../../../pvlib/data/variables_style_rules.csv + :file: ../../../../pvlib/data/variables_style_rules.csv :delim: ; :header-rows: 1 :widths: 5, 5 diff --git a/setup.py b/setup.py index a876f0e995..abc1d3077f 100755 --- a/setup.py +++ b/setup.py @@ -55,7 +55,7 @@ 'pvfactors', 'siphon', 'statsmodels', 'tables', 'cftime >= 1.1.1'], 'doc': ['ipython', 'matplotlib', 'sphinx == 3.1.2', - 'sphinx_rtd_theme==0.5.0', 'sphinx-gallery', 'docutils == 0.15.2', + 'pydata-sphinx-theme', 'sphinx-gallery', 'docutils == 0.15.2', 'pillow', 'netcdf4', 'siphon', 'tables', 'sphinx-toggleprompt >= 0.0.5'], 'test': TESTS_REQUIRE From 9d7ac49cbdf03d4fb65393880836db73578e69bb Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Thu, 15 Apr 2021 18:00:44 -0600 Subject: [PATCH 02/11] stickler --- docs/sphinx/source/conf.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index a1249bf953..a4c322c587 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -133,12 +133,12 @@ # further. For a list of options available for each theme, see the # documentation. html_theme_options = { - #"external_links": [ + # "external_links": [ # {"url": "https://pandas.pydata.org/pandas-docs/stable/", "name": "Pandas Docs"} - #], - #"github_url": "https://github.com/pandas-dev/pydata-sphinx-theme", - #"twitter_url": "https://twitter.com/pandas_dev", - #"use_edit_page_button": True, + # ], + # "github_url": "https://github.com/pandas-dev/pydata-sphinx-theme", + # "twitter_url": "https://twitter.com/pandas_dev", + # "use_edit_page_button": True, "show_toc_level": 1, # "navbar_align": "right", # For testing that the navbar items align properly } From 15a541fca2bfb56f0fbdee674540bb0488274b3e Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Tue, 29 Jun 2021 16:51:05 -0600 Subject: [PATCH 03/11] fix "view on github" links --- .../sphinx/source/_templates/breadcrumbs.html | 26 ----------------- .../source/_templates/edit-this-page.html | 19 ++++++++++++ docs/sphinx/source/conf.py | 29 +++++++++---------- 3 files changed, 33 insertions(+), 41 deletions(-) delete mode 100644 docs/sphinx/source/_templates/breadcrumbs.html create mode 100644 docs/sphinx/source/_templates/edit-this-page.html diff --git a/docs/sphinx/source/_templates/breadcrumbs.html b/docs/sphinx/source/_templates/breadcrumbs.html deleted file mode 100644 index b2078c9119..0000000000 --- a/docs/sphinx/source/_templates/breadcrumbs.html +++ /dev/null @@ -1,26 +0,0 @@ -{# - -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. - -We need to generate the target URL differently based on the type -of page. We use the built-in `pagename` variable to determine what -kind of page this is. `pagename` is the path at the end of the -URL, without the extension. For instance, -https://pvlib-python.rtfd.org/en/stable/auto_examples/plot_singlediode.html -will have pagename = "auto_examples/plot_singlediode". - -Note: make_github_url is defined in conf.py -#} - -{% extends "!breadcrumbs.html" %} -{% block breadcrumbs_aside %} -
  • - {# Get the appropriate GH link based on this page's name: #} - {% set target_url = make_github_url(pagename) %} - {# Create the HTML element with our custom GH link: #} - View on Github -
    • -{% endblock %} diff --git a/docs/sphinx/source/_templates/edit-this-page.html b/docs/sphinx/source/_templates/edit-this-page.html new file mode 100644 index 0000000000..66a09f1e2c --- /dev/null +++ b/docs/sphinx/source/_templates/edit-this-page.html @@ -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('.') %} +
    + + {{ _("View on GitHub") }} + +
    +{% endif %} diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index 899a48878f..5aa913ffb6 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -136,9 +136,9 @@ # "external_links": [ # {"url": "https://pandas.pydata.org/pandas-docs/stable/", "name": "Pandas Docs"} # ], - # "github_url": "https://github.com/pandas-dev/pydata-sphinx-theme", + "github_url": "https://github.com/pvlib/pvlib-python", # "twitter_url": "https://twitter.com/pandas_dev", - # "use_edit_page_button": True, + "use_edit_page_button": True, "show_toc_level": 1, # "navbar_align": "right", # For testing that the navbar items align properly } @@ -399,32 +399,30 @@ def get_linenos(obj): return start, start + len(lines) - 1 -def make_github_url(pagename): +def make_github_url(file_name): """ Generate the appropriate GH link for a given docs page. This function is intended for use in sphinx template files. - The target URL is built differently based on the type of page. Sphinx - provides templates with a built-in `pagename` variable that is the path - at the end of the URL, without the extension. For instance, - https://pvlib-python.rtfd.org/en/stable/auto_examples/plot_singlediode.html - will have pagename = "auto_examples/plot_singlediode". + The target URL is built differently based on the type of page. The pydata + sphinx theme has a built-in `file_name` variable that looks like + "/docs/sphinx/source/api.rst" or "generated/pvlib.atmosphere.alt2pres.rst" """ URL_BASE = "https://github.com/pvlib/pvlib-python/blob/master/" # is it a gallery page? - if any(d in pagename for d in sphinx_gallery_conf['gallery_dirs']): - if pagename.split("/")[-1] == "index": + if any(d in file_name for d in sphinx_gallery_conf['gallery_dirs']): + if file_name.split("/")[-1] == "index": example_file = "README.rst" else: - example_file = pagename.split("/")[-1] + ".py" + example_file = file_name.split("/")[-1].replace('.rst', '.py') target_url = URL_BASE + "docs/examples/" + example_file # is it an API autogen page? - elif "generated" in pagename: - # pagename looks like "generated/pvlib.location.Location" - qualname = pagename.split("/")[-1] + elif "generated" in file_name: + # pagename looks like "generated/pvlib.atmosphere.alt2pres.rst" + qualname = file_name.split("/")[-1].replace('.rst', '') obj, module = get_obj_module(qualname) path = module.__name__.replace(".", "/") + ".py" target_url = URL_BASE + path @@ -435,7 +433,7 @@ def make_github_url(pagename): # Just a normal source RST page else: - target_url = URL_BASE + "docs/sphinx/source/" + pagename + ".rst" + target_url = URL_BASE + "docs/sphinx/source/" + file_name return target_url @@ -444,4 +442,5 @@ def make_github_url(pagename): # _templates/breadcrumbs.html html_context = { 'make_github_url': make_github_url, + 'edit_page_url_template': '{{ make_github_url(file_name) }}', } From f794fefb684e81a435ffe81f1152d14bec0f319f Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Tue, 29 Jun 2021 16:55:20 -0600 Subject: [PATCH 04/11] misc edits --- docs/sphinx/source/conf.py | 3 ++- docs/sphinx/source/user_guide/index.rst | 1 - 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index 5aa913ffb6..8bae6e99d8 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -141,6 +141,7 @@ "use_edit_page_button": True, "show_toc_level": 1, # "navbar_align": "right", # For testing that the navbar items align properly + # "icon_links": [], } # Add any paths that contain custom themes here, relative to this directory. @@ -155,7 +156,7 @@ # The name of an image file (relative to this directory) to place at the top # of the sidebar. -#html_logo = None +html_logo = '_images/pvlib_logo_horiz.png' # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 diff --git a/docs/sphinx/source/user_guide/index.rst b/docs/sphinx/source/user_guide/index.rst index 432b7de7a7..1ee6059acb 100644 --- a/docs/sphinx/source/user_guide/index.rst +++ b/docs/sphinx/source/user_guide/index.rst @@ -5,7 +5,6 @@ User Guide .. toctree:: :maxdepth: 2 - :caption: Demo Documentation package_overview installation From 37a71459fbd06394ae1b70baa6bb5d2159d9a46d Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Wed, 11 Aug 2021 16:36:25 -0600 Subject: [PATCH 05/11] stickler --- docs/sphinx/source/conf.py | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index 8bae6e99d8..54216f8a57 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -132,16 +132,11 @@ # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. +# https://pydata-sphinx-theme.rtfd.io/en/latest/user_guide/configuring.html html_theme_options = { - # "external_links": [ - # {"url": "https://pandas.pydata.org/pandas-docs/stable/", "name": "Pandas Docs"} - # ], "github_url": "https://github.com/pvlib/pvlib-python", - # "twitter_url": "https://twitter.com/pandas_dev", "use_edit_page_button": True, "show_toc_level": 1, - # "navbar_align": "right", # For testing that the navbar items align properly - # "icon_links": [], } # Add any paths that contain custom themes here, relative to this directory. From 8a9a7e3f0bdc6c1c9b165ba7048148b8709add3f Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Wed, 11 Aug 2021 17:19:19 -0600 Subject: [PATCH 06/11] add favicons (!) --- docs/sphinx/source/_static/favicon-16x16.png | Bin 0 -> 854 bytes docs/sphinx/source/_static/favicon-32x32.png | Bin 0 -> 2352 bytes docs/sphinx/source/conf.py | 4 ++++ 3 files changed, 4 insertions(+) create mode 100644 docs/sphinx/source/_static/favicon-16x16.png create mode 100644 docs/sphinx/source/_static/favicon-32x32.png diff --git a/docs/sphinx/source/_static/favicon-16x16.png b/docs/sphinx/source/_static/favicon-16x16.png new file mode 100644 index 0000000000000000000000000000000000000000..c6b8e9618a4ec789d07e1cca0967799bfd44adc7 GIT binary patch literal 854 zcmV-c1F8IpP)yR?1#{{L^^j-MB}#caWI`Q&*{&Utc< zqO1V0QB~C~ilQh+d~T01Go80I2R5(VUj-mX8}7XZJg)j(wzT)G8(1p_eGw_;^AA1D z#{VwRW3e5;qpGVUD~Da3nzwQ$-ChyXueLO%Y72?S<4?#$;)U$JdmpYM$jr~~N;xVF z(SNQ<_I{yh7v4k<6(ao~BbxINzOqFz+~83ir5WSTJFov&@&;f%utw|q-kWy5MrN#r zt;YkH}MjPtAuDZ*l3{<8vW7UifcJpO* zfc#@_EQf3P#(I&VP&dY}Rz%=)HSH-EV!(S7*tVo%y%=x=v>)~o`^CYlZ(G^-zJr&| zRlKzCTg(MccIMR(y;_fU!G!3u4kZ$aryh7u#CB^zPqo%{YFZDU_!_n(*xv4DPIJhUCx6{Cby@~o-{=0yNL8x2+_C~JyM1qE=08MNBD{t zW!M@@*^3r4v$MNaCvk4>6Jz@J8^9y#`BFpl+Xgl7XLF*xBq4_Cf~oow#A2}xM)Yp3 zoSi9tXeW}%WR7;R{U)$6-Q%oPJ8jLtIxW~TE`)gQe|oq~ut`d}O;HrZh(^uXsapsC gefCyh>&pFq04!BVcszx1OaK4?07*qoM6N<$f}qTuk^lez literal 0 HcmV?d00001 diff --git a/docs/sphinx/source/_static/favicon-32x32.png b/docs/sphinx/source/_static/favicon-32x32.png new file mode 100644 index 0000000000000000000000000000000000000000..ae109e9a70795f7efe4c0016445d83ad56ae8d89 GIT binary patch literal 2352 zcmV-03D5S4P)JZv2Y>80>dy?jrDBn)~)x9=iB2l&bdEh?A0IQ%-WYjI$Dp8@&0Tf#In0a zfHCIAI@<~7eEJ9m;6AOUct|bT!(>_h-3U%8eVSctvk4*Q-!%f7rahwMCP1qzxj`wN zXfl~hLWuctdIY4{6&Ps)fQR*#x^JY^_rN*#`B}jjW1gz2K72biG&J;pUX^LsH~NEi zG1e&o?_Z&w)}H1477OZ~q2>2RY~dKS_WP@`M<$ z+WF1z5&=AXYwkci`6SS?wVCPD| zlXoqJ<2_%f1<_8%nCG|&m`o-UyKyyJ+A$YOk}uRWZ|Db>gExN+S~>;1TYl7 zHQPtC2XL>=W_wWA^*=Ml+^tsYuT3VC$z&KtB<(ma)Z%ofR+CTlQ>BBn{YW?ax*9IMU{Xd0>h$_dF1&Np#5QB*UG5FhzSiBosg~j0(boN{auU`yW?gvs5 z1a|2#ryVty^wVVndfi^4mh5(tmL@0XJPyG3(^60xq#d%T_P2c@Mf*ZYGDFSq1aD0T z09Xfx@cQ~91g*+OOKTr??5@YcFbfujS@7?ua$N4aiI6u75b|aL+B^G)+tOVIEz1*1 ziVviZd|}^YhEkZo7*W@Z-FL>^^)pr1t-x!Mg)V;Zs%$vz9iSC6p=D1U)aY+UQGrnMVx9V_h7Q9pwvJYU5c0Ue$p+fl)IuAQ4SoL-h%5B~ zfJ@y22wt6oz|brNg=gc-_I@N}G$1fE3xT0oh=?jj|1~?7t;_FxkOVh|K=8NHu8KLOXR{a_WI(DNrlP4|Mba{*{)Qzw8Y#tcp=eVUxD zzwCJbIY`@lp``dg%kl&}9Ss0zZtX+x>Kp{E%Es~2J%~;@iiIn)uyAD-)^09E+a)WO zt;@%vFbgVchj$OZkPgk_0p$}PNZbA3*gOOJ=LZM>?`MT`K9jbdwMp^oq2z9XR+#{L zBEz6(^FV9f0z1AIyy+F3XzqnqPzv6UtA=?=>S)IQm=lM%^kZU#@ zv@Qa)c{k|EOhY@I1hpUvQbHv3Qw^FBB4niJ_X#0Z3L%zp&Sx>k+;m-k)Mm3iO3#%@ z>TWOSdG4T1LcYP~+3`LPwy3noL$@B%rJ zCKzLrG);SiG3LfO_ZLDeH4I~o!{PYNkLrQTwyny}=b@ySq3-blIrtJpPX*X#^B~%` z4bS?a3lIa1x8{B(*kON&u0qh7b%#X7-YOyM5ylD0y3*TusxoN0fcZP>K>6IG=rs=*x0SI2_x8VQ{kHR;8ZR ztMepj*SlbhP5D{D#xg}wCh1LePND1JBbd!*dr+&))s(_SCn4mq5nKons5RCILde}a zn(4Yeopb*24{_Rkv79uY`0|IiVHj@-A(r1Y0stOx`GLG;LWt!C=bOe_bH^cboBa>J W=f`jCcw@u>0000 Date: Wed, 11 Aug 2021 17:19:59 -0600 Subject: [PATCH 07/11] header icons for stackoverflow, google group, pypi --- docs/sphinx/source/conf.py | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index 7567ee680b..0a7765ebf2 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -139,6 +139,23 @@ {"rel": "icon", "sizes": "16x16", "href": "favicon-16x16.png"}, {"rel": "icon", "sizes": "32x32", "href": "favicon-32x32.png"}, ], + "icon_links": [ + { + "name": "StackOverflow", + "url": "https://stackoverflow.com/questions/tagged/pvlib", + "icon": "fab fa-stack-overflow", + }, + { + "name": "Google Group", + "url": "https://groups.google.com/g/pvlib-python", + "icon": "fab fa-google", + }, + { + "name": "PyPI", + "url": "https://pypi.org/project/pvlib/", + "icon": "fab fa-python", + }, + ], "use_edit_page_button": True, "show_toc_level": 1, } From 7762ca8182a37c1560482ef00d2caaf3a683378c Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Wed, 11 Aug 2021 17:20:34 -0600 Subject: [PATCH 08/11] bump copyright year to 2021 --- docs/sphinx/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index 0a7765ebf2..482fde83eb 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -70,7 +70,7 @@ # General information about the project. project = 'pvlib python' copyright = \ - '2013-2020, Sandia National Laboratories and pvlib python Development Team' + '2013-2021, Sandia National Laboratories and pvlib python Development Team' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the From d1309ae597447fe604aa37e4822df7e646a948c3 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Wed, 11 Aug 2021 18:08:54 -0600 Subject: [PATCH 09/11] clean up left sidebar by breaking out api sections into separate files --- .gitignore | 2 +- docs/sphinx/Makefile | 2 +- docs/sphinx/make.bat | 2 +- docs/sphinx/source/api.rst | 715 ------------------ docs/sphinx/source/conf.py | 2 +- docs/sphinx/source/index.rst | 2 +- .../source/reference/airmass_atmospheric.rst | 19 + docs/sphinx/source/reference/bifacial.rst | 11 + docs/sphinx/source/reference/classes.rst | 24 + docs/sphinx/source/reference/clearsky.rst | 15 + .../reference/effects_on_pv_system_output.rst | 50 ++ docs/sphinx/source/reference/forecasting.rst | 57 ++ docs/sphinx/source/reference/index.rst | 22 + docs/sphinx/source/reference/iotools.rst | 48 ++ docs/sphinx/source/reference/irradiance.rst | 70 ++ docs/sphinx/source/reference/modelchain.rst | 128 ++++ docs/sphinx/source/reference/pv_modeling.rst | 186 +++++ docs/sphinx/source/reference/scaling.rst | 11 + .../sphinx/source/reference/solarposition.rst | 66 ++ docs/sphinx/source/reference/tracking.rst | 27 + 20 files changed, 739 insertions(+), 720 deletions(-) delete mode 100644 docs/sphinx/source/api.rst create mode 100644 docs/sphinx/source/reference/airmass_atmospheric.rst create mode 100644 docs/sphinx/source/reference/bifacial.rst create mode 100644 docs/sphinx/source/reference/classes.rst create mode 100644 docs/sphinx/source/reference/clearsky.rst create mode 100644 docs/sphinx/source/reference/effects_on_pv_system_output.rst create mode 100644 docs/sphinx/source/reference/forecasting.rst create mode 100644 docs/sphinx/source/reference/index.rst create mode 100644 docs/sphinx/source/reference/iotools.rst create mode 100644 docs/sphinx/source/reference/irradiance.rst create mode 100644 docs/sphinx/source/reference/modelchain.rst create mode 100644 docs/sphinx/source/reference/pv_modeling.rst create mode 100644 docs/sphinx/source/reference/scaling.rst create mode 100644 docs/sphinx/source/reference/solarposition.rst create mode 100644 docs/sphinx/source/reference/tracking.rst diff --git a/.gitignore b/.gitignore index 1667960d27..99f36a592a 100644 --- a/.gitignore +++ b/.gitignore @@ -39,7 +39,7 @@ 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 diff --git a/docs/sphinx/Makefile b/docs/sphinx/Makefile index 0c96b4ed23..5259b055ca 100644 --- a/docs/sphinx/Makefile +++ b/docs/sphinx/Makefile @@ -48,7 +48,7 @@ help: clean: rm -rf $(BUILDDIR)/* - rm -rf source/generated + rm -rf source/reference/generated rm -rf source/auto_examples rm -rf source/savefig diff --git a/docs/sphinx/make.bat b/docs/sphinx/make.bat index d12b216553..553a5ae932 100644 --- a/docs/sphinx/make.bat +++ b/docs/sphinx/make.bat @@ -17,7 +17,7 @@ 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%\reference\generated >nul 2>&1 rmdir /q /s %SOURCEDIR%\auto_examples >nul 2>&1 rmdir /q /s %SOURCEDIR%\savefig >nul 2>&1 goto end diff --git a/docs/sphinx/source/api.rst b/docs/sphinx/source/api.rst deleted file mode 100644 index 6d08e742b3..0000000000 --- a/docs/sphinx/source/api.rst +++ /dev/null @@ -1,715 +0,0 @@ -.. currentmodule:: pvlib - -############# -API reference -############# - - -Classes -======= - -pvlib-python provides a collection of classes for users that prefer -object-oriented programming. These classes can help users keep track of -data in a more organized way, and can help to simplify the modeling -process. The classes do not add any functionality beyond the procedural -code. Most of the object methods are simple wrappers around the -corresponding procedural code. For examples of using these classes, see -the :ref:`pvsystemdoc` and :ref:`modelchaindoc` pages. - -.. autosummary:: - :toctree: generated/ - - location.Location - pvsystem.PVSystem - pvsystem.Array - pvsystem.FixedMount - pvsystem.SingleAxisTrackerMount - tracking.SingleAxisTracker - modelchain.ModelChain - modelchain.ModelChainResult - -Solar Position -============== - -Functions and methods for calculating solar position. - -The :py:meth:`location.Location.get_solarposition` method and the -:py:func:`solarposition.get_solarposition` function with default -parameters are fast and accurate. We recommend using these functions -unless you know that you need a different function. - -.. autosummary:: - :toctree: generated/ - - location.Location.get_solarposition - solarposition.get_solarposition - solarposition.spa_python - solarposition.ephemeris - solarposition.pyephem - solarposition.spa_c - - -Additional functions for quantities closely related to solar position. - -.. autosummary:: - :toctree: generated/ - - solarposition.calc_time - solarposition.pyephem_earthsun_distance - solarposition.nrel_earthsun_distance - spa.calculate_deltat - - -Functions for calculating sunrise, sunset and transit times. - -.. autosummary:: - :toctree: generated/ - - location.Location.get_sun_rise_set_transit - solarposition.sun_rise_set_transit_ephem - solarposition.sun_rise_set_transit_spa - solarposition.sun_rise_set_transit_geometric - - -The spa module contains the implementation of the built-in NREL SPA -algorithm. - -.. autosummary:: - :toctree: generated/ - - spa - -Correlations and analytical expressions for low precision solar position -calculations. - -.. autosummary:: - :toctree: generated/ - - solarposition.solar_zenith_analytical - solarposition.solar_azimuth_analytical - solarposition.declination_spencer71 - solarposition.declination_cooper69 - solarposition.equation_of_time_spencer71 - solarposition.equation_of_time_pvcdrom - solarposition.hour_angle - - -Clear sky -========= - -.. autosummary:: - :toctree: generated/ - - location.Location.get_clearsky - clearsky.ineichen - clearsky.lookup_linke_turbidity - clearsky.simplified_solis - clearsky.haurwitz - clearsky.detect_clearsky - clearsky.bird - - -Airmass and atmospheric models -============================== - -.. autosummary:: - :toctree: generated/ - - location.Location.get_airmass - atmosphere.get_absolute_airmass - atmosphere.get_relative_airmass - atmosphere.pres2alt - atmosphere.alt2pres - atmosphere.gueymard94_pw - atmosphere.first_solar_spectral_correction - atmosphere.bird_hulstrom80_aod_bb - atmosphere.kasten96_lt - atmosphere.angstrom_aod_at_lambda - atmosphere.angstrom_alpha - - -Irradiance -========== - -Methods for irradiance calculations ------------------------------------ - -.. autosummary:: - :toctree: generated/ - - pvsystem.PVSystem.get_irradiance - pvsystem.PVSystem.get_aoi - pvsystem.PVSystem.get_iam - tracking.SingleAxisTracker.get_irradiance - -Decomposing and combining irradiance ------------------------------------- - -.. autosummary:: - :toctree: generated/ - - irradiance.get_extra_radiation - irradiance.aoi - irradiance.aoi_projection - irradiance.poa_horizontal_ratio - irradiance.beam_component - irradiance.poa_components - irradiance.get_ground_diffuse - irradiance.dni - -Transposition models --------------------- - -.. autosummary:: - :toctree: generated/ - - irradiance.get_total_irradiance - irradiance.get_sky_diffuse - irradiance.isotropic - irradiance.perez - irradiance.haydavies - irradiance.klucher - irradiance.reindl - irradiance.king - -.. _dniestmodels: - -DNI estimation models ---------------------- - -.. autosummary:: - :toctree: generated/ - - irradiance.disc - irradiance.dirint - irradiance.dirindex - irradiance.erbs - irradiance.campbell_norman - irradiance.gti_dirint - -Clearness index models ----------------------- - -.. autosummary:: - :toctree: generated/ - - irradiance.clearness_index - irradiance.clearness_index_zenith_independent - irradiance.clearsky_index - - -PV Modeling -=========== - -Classes -------- - -The :py:class:`~pvsystem.PVSystem` class provides many methods that -wrap the functions listed below. See its documentation for details. - -.. autosummary:: - :toctree: generated/ - - pvsystem.PVSystem - -Incident angle modifiers ------------------------- - -.. autosummary:: - :toctree: generated/ - - iam.physical - iam.ashrae - iam.martin_ruiz - iam.martin_ruiz_diffuse - iam.sapm - iam.interp - iam.marion_diffuse - iam.marion_integrate - -PV temperature models ---------------------- - -.. autosummary:: - :toctree: generated/ - - temperature.sapm_cell - temperature.sapm_module - temperature.sapm_cell_from_module - temperature.pvsyst_cell - temperature.faiman - temperature.fuentes - temperature.ross - temperature.noct_sam - pvsystem.PVSystem.get_cell_temperature - -Temperature Model Parameters -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. currentmodule:: pvlib.temperature -.. autodata:: TEMPERATURE_MODEL_PARAMETERS - :annotation: - -.. currentmodule:: pvlib - -Single diode models -------------------- - -Functions relevant for single diode models. - -.. autosummary:: - :toctree: generated/ - - pvsystem.calcparams_cec - pvsystem.calcparams_desoto - pvsystem.calcparams_pvsyst - pvsystem.i_from_v - pvsystem.singlediode - pvsystem.v_from_i - pvsystem.max_power_point - ivtools.sdm.pvsyst_temperature_coeff - -Low-level functions for solving the single diode equation. - -.. autosummary:: - :toctree: generated/ - - singlediode.estimate_voc - singlediode.bishop88 - singlediode.bishop88_i_from_v - singlediode.bishop88_v_from_i - singlediode.bishop88_mpp - -Functions for fitting diode models - -.. autosummary:: - :toctree: generated/ - - ivtools.sde.fit_sandia_simple - ivtools.sdm.fit_cec_sam - ivtools.sdm.fit_desoto - -Inverter models (DC to AC conversion) -------------------------------------- - -.. autosummary:: - :toctree: generated/ - - pvsystem.PVSystem.get_ac - inverter.sandia - inverter.sandia_multi - inverter.adr - inverter.pvwatts - inverter.pvwatts_multi - -Functions for fitting inverter models - -.. autosummary:: - :toctree: generated/ - - inverter.fit_sandia - - -PV System Models ----------------- - -Sandia array performance model (SAPM) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. autosummary:: - :toctree: generated/ - - pvsystem.sapm - pvsystem.sapm_effective_irradiance - pvsystem.sapm_spectral_loss - inverter.sandia - temperature.sapm_cell - -Pvsyst model -^^^^^^^^^^^^ - -.. autosummary:: - :toctree: generated/ - - temperature.pvsyst_cell - pvsystem.calcparams_pvsyst - pvsystem.singlediode - ivtools.sdm.pvsyst_temperature_coeff - pvsystem.dc_ohms_from_percent - pvsystem.dc_ohmic_losses - -PVWatts model -^^^^^^^^^^^^^ - -.. autosummary:: - :toctree: generated/ - - pvsystem.pvwatts_dc - inverter.pvwatts - pvsystem.pvwatts_losses - -Estimating PV model parameters ------------------------------- - -Functions for fitting single diode models - -.. autosummary:: - :toctree: generated/ - - ivtools.sdm.fit_cec_sam - ivtools.sdm.fit_desoto - ivtools.sdm.fit_pvsyst_sandia - ivtools.sdm.fit_desoto_sandia - -Functions for fitting the single diode equation - -.. autosummary:: - :toctree: generated/ - - ivtools.sde.fit_sandia_simple - -Utilities for working with IV curve data - -.. autosummary:: - :toctree: generated/ - - ivtools.utils.rectify_iv_curve - -Other ------ - -.. autosummary:: - :toctree: generated/ - - pvsystem.retrieve_sam - pvsystem.scale_voltage_current_power - - -Effects on PV System Output -=========================== - -Loss models ------------ - -.. autosummary:: - :toctree: generated/ - - pvsystem.combine_loss_factors - pvsystem.dc_ohms_from_percent - -Snow ----- - -.. autosummary:: - :toctree: generated/ - - snow.coverage_nrel - snow.fully_covered_nrel - snow.dc_loss_nrel - -Soiling -------- - -.. autosummary:: - :toctree: generated/ - - soiling.hsu - soiling.kimber - -Shading -------- - -.. autosummary:: - :toctree: generated/ - - shading.masking_angle - shading.masking_angle_passias - shading.sky_diffuse_passias - -Spectrum --------- - -.. autosummary:: - :toctree: generated/ - - spectrum.spectrl2 - -Tracking -======== - -SingleAxisTracker ------------------ - -The :py:class:`~tracking.SingleAxisTracker` inherits from -:py:class:`~pvsystem.PVSystem`. - -.. autosummary:: - :toctree: generated/ - - tracking.SingleAxisTracker - tracking.SingleAxisTracker.singleaxis - tracking.SingleAxisTracker.get_irradiance - -Functions ---------- - -.. autosummary:: - :toctree: generated/ - - tracking.singleaxis - tracking.calc_axis_tilt - tracking.calc_cross_axis_tilt - - -.. _iotools: - -IO Tools -======== - -Functions for retrieving, reading, and writing data from a variety -of sources and file formats relevant to solar energy modeling. - -.. autosummary:: - :toctree: generated/ - - iotools.read_tmy2 - iotools.read_tmy3 - iotools.read_epw - iotools.parse_epw - iotools.read_srml - iotools.read_srml_month_from_solardat - iotools.read_surfrad - iotools.read_midc - iotools.read_midc_raw_data_from_nrel - iotools.read_ecmwf_macc - iotools.get_ecmwf_macc - iotools.read_crn - iotools.read_solrad - iotools.get_psm3 - iotools.read_psm3 - iotools.parse_psm3 - iotools.get_pvgis_tmy - iotools.read_pvgis_tmy - iotools.get_pvgis_hourly - iotools.read_pvgis_hourly - iotools.get_bsrn - iotools.read_bsrn - iotools.parse_bsrn - iotools.get_cams - iotools.read_cams - iotools.parse_cams - -A :py:class:`~pvlib.location.Location` object may be created from metadata -in some files. - -.. autosummary:: - :toctree: generated/ - - location.Location.from_tmy - location.Location.from_epw - - -Forecasting -=========== - -Forecast models ---------------- - -.. autosummary:: - :toctree: generated/ - - forecast.GFS - forecast.NAM - forecast.RAP - forecast.HRRR - forecast.HRRR_ESRL - forecast.NDFD - -Getting data ------------- - -.. autosummary:: - :toctree: generated/ - - forecast.ForecastModel.get_data - forecast.ForecastModel.get_processed_data - -Processing data ---------------- - -.. autosummary:: - :toctree: generated/ - - forecast.ForecastModel.process_data - forecast.ForecastModel.rename - forecast.ForecastModel.cloud_cover_to_ghi_linear - forecast.ForecastModel.cloud_cover_to_irradiance_clearsky_scaling - forecast.ForecastModel.cloud_cover_to_transmittance_linear - forecast.ForecastModel.cloud_cover_to_irradiance_campbell_norman - forecast.ForecastModel.cloud_cover_to_irradiance - forecast.ForecastModel.kelvin_to_celsius - forecast.ForecastModel.isobaric_to_ambient_temperature - forecast.ForecastModel.uv_to_speed - forecast.ForecastModel.gust_to_speed - -IO support ----------- - -These are public for now, but use at your own risk. - -.. autosummary:: - :toctree: generated/ - - forecast.ForecastModel.set_dataset - forecast.ForecastModel.set_query_latlon - forecast.ForecastModel.set_location - forecast.ForecastModel.set_time - - -ModelChain -========== - -Creating a ModelChain object. - -.. autosummary:: - :toctree: generated/ - - modelchain.ModelChain - modelchain.ModelChain.with_pvwatts - modelchain.ModelChain.with_sapm - -.. _modelchain_runmodel: - -Running -------- - -A ModelChain can be run from a number of starting points, depending on the -input data available. - -.. autosummary:: - :toctree: generated/ - - modelchain.ModelChain.run_model - modelchain.ModelChain.run_model_from_poa - modelchain.ModelChain.run_model_from_effective_irradiance - -Functions to assist with setting up ModelChains to run - -.. autosummary:: - :toctree: generated/ - - modelchain.ModelChain.complete_irradiance - modelchain.ModelChain.prepare_inputs - modelchain.ModelChain.prepare_inputs_from_poa - -Results -------- - -Output from the running the ModelChain is stored in the -:py:attr:`modelchain.ModelChain.results` attribute. For more -information see :py:class:`modelchain.ModelChainResult`. - -Attributes ----------- - -Simple ModelChain attributes: - -``system, location, clearsky_model, transposition_model, -solar_position_method, airmass_model`` - -Properties ----------- - -ModelChain properties that are aliases for your specific modeling functions. - -.. autosummary:: - :toctree: generated/ - - modelchain.ModelChain.dc_model - modelchain.ModelChain.ac_model - modelchain.ModelChain.aoi_model - modelchain.ModelChain.spectral_model - modelchain.ModelChain.temperature_model - modelchain.ModelChain.dc_ohmic_model - modelchain.ModelChain.losses_model - modelchain.ModelChain.effective_irradiance_model - -Model definitions ------------------ - -ModelChain model definitions. - -.. autosummary:: - :toctree: generated/ - - modelchain.ModelChain.sapm - modelchain.ModelChain.cec - modelchain.ModelChain.desoto - modelchain.ModelChain.pvsyst - modelchain.ModelChain.pvwatts_dc - modelchain.ModelChain.sandia_inverter - modelchain.ModelChain.adr_inverter - modelchain.ModelChain.pvwatts_inverter - modelchain.ModelChain.ashrae_aoi_loss - modelchain.ModelChain.physical_aoi_loss - modelchain.ModelChain.sapm_aoi_loss - modelchain.ModelChain.no_aoi_loss - modelchain.ModelChain.first_solar_spectral_loss - modelchain.ModelChain.sapm_spectral_loss - modelchain.ModelChain.no_spectral_loss - modelchain.ModelChain.sapm_temp - modelchain.ModelChain.pvsyst_temp - modelchain.ModelChain.faiman_temp - modelchain.ModelChain.fuentes_temp - modelchain.ModelChain.dc_ohmic_model - modelchain.ModelChain.no_dc_ohmic_loss - modelchain.ModelChain.pvwatts_losses - modelchain.ModelChain.no_extra_losses - -Inference methods ------------------ - -Methods that automatically determine which models should be used based -on the information in the associated :py:class:`~pvsystem.PVSystem` object. - -.. autosummary:: - :toctree: generated/ - - modelchain.ModelChain.infer_dc_model - modelchain.ModelChain.infer_ac_model - modelchain.ModelChain.infer_aoi_model - modelchain.ModelChain.infer_spectral_model - modelchain.ModelChain.infer_temperature_model - modelchain.ModelChain.infer_losses_model - -Functions ---------- - -Functions for power modeling. - -.. autosummary:: - :toctree: generated/ - - modelchain.basic_chain - modelchain.get_orientation - - -Bifacial -======== - -Methods for calculating back surface irradiance - -.. autosummary:: - :toctree: generated/ - - bifacial.pvfactors_timeseries - - -Scaling -======= - -Methods for manipulating irradiance for temporal or spatial considerations - -.. autosummary:: - :toctree: generated/ - - scaling.wvm diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index 482fde83eb..20ce760cbb 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -355,7 +355,7 @@ def setup(app): # 'filename_pattern': '*.py', # directory where function/class granular galleries are stored - 'backreferences_dir': 'generated/gallery_backreferences', + 'backreferences_dir': 'reference/generated/gallery_backreferences', # Modules for which function/class level galleries are created. In # this case only pvlib, could include others though. must be tuple of str diff --git a/docs/sphinx/source/index.rst b/docs/sphinx/source/index.rst index 4a7f282a93..89353268fc 100644 --- a/docs/sphinx/source/index.rst +++ b/docs/sphinx/source/index.rst @@ -92,7 +92,7 @@ Contents user_guide/index auto_examples/index - api + reference/index whatsnew contributing diff --git a/docs/sphinx/source/reference/airmass_atmospheric.rst b/docs/sphinx/source/reference/airmass_atmospheric.rst new file mode 100644 index 0000000000..fbd33a5f28 --- /dev/null +++ b/docs/sphinx/source/reference/airmass_atmospheric.rst @@ -0,0 +1,19 @@ +.. currentmodule:: pvlib + +Airmass and atmospheric models +============================== + +.. autosummary:: + :toctree: generated/ + + location.Location.get_airmass + atmosphere.get_absolute_airmass + atmosphere.get_relative_airmass + atmosphere.pres2alt + atmosphere.alt2pres + atmosphere.gueymard94_pw + atmosphere.first_solar_spectral_correction + atmosphere.bird_hulstrom80_aod_bb + atmosphere.kasten96_lt + atmosphere.angstrom_aod_at_lambda + atmosphere.angstrom_alpha diff --git a/docs/sphinx/source/reference/bifacial.rst b/docs/sphinx/source/reference/bifacial.rst new file mode 100644 index 0000000000..f19195429f --- /dev/null +++ b/docs/sphinx/source/reference/bifacial.rst @@ -0,0 +1,11 @@ +.. currentmodule:: pvlib + +Bifacial +======== + +Methods for calculating back surface irradiance + +.. autosummary:: + :toctree: generated/ + + bifacial.pvfactors_timeseries diff --git a/docs/sphinx/source/reference/classes.rst b/docs/sphinx/source/reference/classes.rst new file mode 100644 index 0000000000..d96db6422d --- /dev/null +++ b/docs/sphinx/source/reference/classes.rst @@ -0,0 +1,24 @@ +.. currentmodule:: pvlib + +Classes +======= + +pvlib-python provides a collection of classes for users that prefer +object-oriented programming. These classes can help users keep track of +data in a more organized way, and can help to simplify the modeling +process. The classes do not add any functionality beyond the procedural +code. Most of the object methods are simple wrappers around the +corresponding procedural code. For examples of using these classes, see +the :ref:`pvsystemdoc` and :ref:`modelchaindoc` pages. + +.. autosummary:: + :toctree: generated/ + + location.Location + pvsystem.PVSystem + pvsystem.Array + pvsystem.FixedMount + pvsystem.SingleAxisTrackerMount + tracking.SingleAxisTracker + modelchain.ModelChain + modelchain.ModelChainResult diff --git a/docs/sphinx/source/reference/clearsky.rst b/docs/sphinx/source/reference/clearsky.rst new file mode 100644 index 0000000000..e81372cc2d --- /dev/null +++ b/docs/sphinx/source/reference/clearsky.rst @@ -0,0 +1,15 @@ +.. currentmodule:: pvlib + +Clear sky +========= + +.. autosummary:: + :toctree: generated/ + + location.Location.get_clearsky + clearsky.ineichen + clearsky.lookup_linke_turbidity + clearsky.simplified_solis + clearsky.haurwitz + clearsky.detect_clearsky + clearsky.bird diff --git a/docs/sphinx/source/reference/effects_on_pv_system_output.rst b/docs/sphinx/source/reference/effects_on_pv_system_output.rst new file mode 100644 index 0000000000..92efa946b4 --- /dev/null +++ b/docs/sphinx/source/reference/effects_on_pv_system_output.rst @@ -0,0 +1,50 @@ +.. currentmodule:: pvlib + +Effects on PV System Output +=========================== + +Loss models +----------- + +.. autosummary:: + :toctree: generated/ + + pvsystem.combine_loss_factors + pvsystem.dc_ohms_from_percent + +Snow +---- + +.. autosummary:: + :toctree: generated/ + + snow.coverage_nrel + snow.fully_covered_nrel + snow.dc_loss_nrel + +Soiling +------- + +.. autosummary:: + :toctree: generated/ + + soiling.hsu + soiling.kimber + +Shading +------- + +.. autosummary:: + :toctree: generated/ + + shading.masking_angle + shading.masking_angle_passias + shading.sky_diffuse_passias + +Spectrum +-------- + +.. autosummary:: + :toctree: generated/ + + spectrum.spectrl2 diff --git a/docs/sphinx/source/reference/forecasting.rst b/docs/sphinx/source/reference/forecasting.rst new file mode 100644 index 0000000000..ff4df7ed4d --- /dev/null +++ b/docs/sphinx/source/reference/forecasting.rst @@ -0,0 +1,57 @@ +.. currentmodule:: pvlib + +Forecasting +=========== + +Forecast models +--------------- + +.. autosummary:: + :toctree: generated/ + + forecast.GFS + forecast.NAM + forecast.RAP + forecast.HRRR + forecast.HRRR_ESRL + forecast.NDFD + +Getting data +------------ + +.. autosummary:: + :toctree: generated/ + + forecast.ForecastModel.get_data + forecast.ForecastModel.get_processed_data + +Processing data +--------------- + +.. autosummary:: + :toctree: generated/ + + forecast.ForecastModel.process_data + forecast.ForecastModel.rename + forecast.ForecastModel.cloud_cover_to_ghi_linear + forecast.ForecastModel.cloud_cover_to_irradiance_clearsky_scaling + forecast.ForecastModel.cloud_cover_to_transmittance_linear + forecast.ForecastModel.cloud_cover_to_irradiance_campbell_norman + forecast.ForecastModel.cloud_cover_to_irradiance + forecast.ForecastModel.kelvin_to_celsius + forecast.ForecastModel.isobaric_to_ambient_temperature + forecast.ForecastModel.uv_to_speed + forecast.ForecastModel.gust_to_speed + +IO support +---------- + +These are public for now, but use at your own risk. + +.. autosummary:: + :toctree: generated/ + + forecast.ForecastModel.set_dataset + forecast.ForecastModel.set_query_latlon + forecast.ForecastModel.set_location + forecast.ForecastModel.set_time diff --git a/docs/sphinx/source/reference/index.rst b/docs/sphinx/source/reference/index.rst new file mode 100644 index 0000000000..0f1902325a --- /dev/null +++ b/docs/sphinx/source/reference/index.rst @@ -0,0 +1,22 @@ +.. currentmodule:: pvlib + +############# +API reference +############# + +.. toctree:: + :maxdepth: 2 + + classes + solarposition + clearsky + airmass_atmospheric + irradiance + pv_modeling + effects_on_pv_system_output + tracking + iotools + forecasting + modelchain + bifacial + scaling diff --git a/docs/sphinx/source/reference/iotools.rst b/docs/sphinx/source/reference/iotools.rst new file mode 100644 index 0000000000..514aeac2f5 --- /dev/null +++ b/docs/sphinx/source/reference/iotools.rst @@ -0,0 +1,48 @@ +.. currentmodule:: pvlib + +.. _iotools: + +IO Tools +======== + +Functions for retrieving, reading, and writing data from a variety +of sources and file formats relevant to solar energy modeling. + +.. autosummary:: + :toctree: generated/ + + iotools.read_tmy2 + iotools.read_tmy3 + iotools.read_epw + iotools.parse_epw + iotools.read_srml + iotools.read_srml_month_from_solardat + iotools.read_surfrad + iotools.read_midc + iotools.read_midc_raw_data_from_nrel + iotools.read_ecmwf_macc + iotools.get_ecmwf_macc + iotools.read_crn + iotools.read_solrad + iotools.get_psm3 + iotools.read_psm3 + iotools.parse_psm3 + iotools.get_pvgis_tmy + iotools.read_pvgis_tmy + iotools.get_pvgis_hourly + iotools.read_pvgis_hourly + iotools.get_bsrn + iotools.read_bsrn + iotools.parse_bsrn + iotools.get_cams + iotools.read_cams + iotools.parse_cams + +A :py:class:`~pvlib.location.Location` object may be created from metadata +in some files. + +.. autosummary:: + :toctree: generated/ + + location.Location.from_tmy + location.Location.from_epw diff --git a/docs/sphinx/source/reference/irradiance.rst b/docs/sphinx/source/reference/irradiance.rst new file mode 100644 index 0000000000..e0a5777533 --- /dev/null +++ b/docs/sphinx/source/reference/irradiance.rst @@ -0,0 +1,70 @@ +.. currentmodule:: pvlib + +Irradiance +========== + +Methods for irradiance calculations +----------------------------------- + +.. autosummary:: + :toctree: generated/ + + pvsystem.PVSystem.get_irradiance + pvsystem.PVSystem.get_aoi + pvsystem.PVSystem.get_iam + tracking.SingleAxisTracker.get_irradiance + +Decomposing and combining irradiance +------------------------------------ + +.. autosummary:: + :toctree: generated/ + + irradiance.get_extra_radiation + irradiance.aoi + irradiance.aoi_projection + irradiance.poa_horizontal_ratio + irradiance.beam_component + irradiance.poa_components + irradiance.get_ground_diffuse + irradiance.dni + +Transposition models +-------------------- + +.. autosummary:: + :toctree: generated/ + + irradiance.get_total_irradiance + irradiance.get_sky_diffuse + irradiance.isotropic + irradiance.perez + irradiance.haydavies + irradiance.klucher + irradiance.reindl + irradiance.king + +.. _dniestmodels: + +DNI estimation models +--------------------- + +.. autosummary:: + :toctree: generated/ + + irradiance.disc + irradiance.dirint + irradiance.dirindex + irradiance.erbs + irradiance.campbell_norman + irradiance.gti_dirint + +Clearness index models +---------------------- + +.. autosummary:: + :toctree: generated/ + + irradiance.clearness_index + irradiance.clearness_index_zenith_independent + irradiance.clearsky_index diff --git a/docs/sphinx/source/reference/modelchain.rst b/docs/sphinx/source/reference/modelchain.rst new file mode 100644 index 0000000000..b8ce6744fb --- /dev/null +++ b/docs/sphinx/source/reference/modelchain.rst @@ -0,0 +1,128 @@ +.. currentmodule:: pvlib + +ModelChain +========== + +Creating a ModelChain object. + +.. autosummary:: + :toctree: generated/ + + modelchain.ModelChain + modelchain.ModelChain.with_pvwatts + modelchain.ModelChain.with_sapm + +.. _modelchain_runmodel: + +Running +------- + +A ModelChain can be run from a number of starting points, depending on the +input data available. + +.. autosummary:: + :toctree: generated/ + + modelchain.ModelChain.run_model + modelchain.ModelChain.run_model_from_poa + modelchain.ModelChain.run_model_from_effective_irradiance + +Functions to assist with setting up ModelChains to run + +.. autosummary:: + :toctree: generated/ + + modelchain.ModelChain.complete_irradiance + modelchain.ModelChain.prepare_inputs + modelchain.ModelChain.prepare_inputs_from_poa + +Results +------- + +Output from the running the ModelChain is stored in the +:py:attr:`modelchain.ModelChain.results` attribute. For more +information see :py:class:`modelchain.ModelChainResult`. + +Attributes +---------- + +Simple ModelChain attributes: + +``system, location, clearsky_model, transposition_model, +solar_position_method, airmass_model`` + +Properties +---------- + +ModelChain properties that are aliases for your specific modeling functions. + +.. autosummary:: + :toctree: generated/ + + modelchain.ModelChain.dc_model + modelchain.ModelChain.ac_model + modelchain.ModelChain.aoi_model + modelchain.ModelChain.spectral_model + modelchain.ModelChain.temperature_model + modelchain.ModelChain.dc_ohmic_model + modelchain.ModelChain.losses_model + modelchain.ModelChain.effective_irradiance_model + +Model definitions +----------------- + +ModelChain model definitions. + +.. autosummary:: + :toctree: generated/ + + modelchain.ModelChain.sapm + modelchain.ModelChain.cec + modelchain.ModelChain.desoto + modelchain.ModelChain.pvsyst + modelchain.ModelChain.pvwatts_dc + modelchain.ModelChain.sandia_inverter + modelchain.ModelChain.adr_inverter + modelchain.ModelChain.pvwatts_inverter + modelchain.ModelChain.ashrae_aoi_loss + modelchain.ModelChain.physical_aoi_loss + modelchain.ModelChain.sapm_aoi_loss + modelchain.ModelChain.no_aoi_loss + modelchain.ModelChain.first_solar_spectral_loss + modelchain.ModelChain.sapm_spectral_loss + modelchain.ModelChain.no_spectral_loss + modelchain.ModelChain.sapm_temp + modelchain.ModelChain.pvsyst_temp + modelchain.ModelChain.faiman_temp + modelchain.ModelChain.fuentes_temp + modelchain.ModelChain.dc_ohmic_model + modelchain.ModelChain.no_dc_ohmic_loss + modelchain.ModelChain.pvwatts_losses + modelchain.ModelChain.no_extra_losses + +Inference methods +----------------- + +Methods that automatically determine which models should be used based +on the information in the associated :py:class:`~pvsystem.PVSystem` object. + +.. autosummary:: + :toctree: generated/ + + modelchain.ModelChain.infer_dc_model + modelchain.ModelChain.infer_ac_model + modelchain.ModelChain.infer_aoi_model + modelchain.ModelChain.infer_spectral_model + modelchain.ModelChain.infer_temperature_model + modelchain.ModelChain.infer_losses_model + +Functions +--------- + +Functions for power modeling. + +.. autosummary:: + :toctree: generated/ + + modelchain.basic_chain + modelchain.get_orientation diff --git a/docs/sphinx/source/reference/pv_modeling.rst b/docs/sphinx/source/reference/pv_modeling.rst new file mode 100644 index 0000000000..dc2f8f1099 --- /dev/null +++ b/docs/sphinx/source/reference/pv_modeling.rst @@ -0,0 +1,186 @@ +.. currentmodule:: pvlib + +PV Modeling +=========== + +Classes +------- + +The :py:class:`~pvsystem.PVSystem` class provides many methods that +wrap the functions listed below. See its documentation for details. + +.. autosummary:: + :toctree: generated/ + + pvsystem.PVSystem + +Incident angle modifiers +------------------------ + +.. autosummary:: + :toctree: generated/ + + iam.physical + iam.ashrae + iam.martin_ruiz + iam.martin_ruiz_diffuse + iam.sapm + iam.interp + iam.marion_diffuse + iam.marion_integrate + +PV temperature models +--------------------- + +.. autosummary:: + :toctree: generated/ + + temperature.sapm_cell + temperature.sapm_module + temperature.sapm_cell_from_module + temperature.pvsyst_cell + temperature.faiman + temperature.fuentes + temperature.ross + temperature.noct_sam + pvsystem.PVSystem.get_cell_temperature + +Temperature Model Parameters +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. currentmodule:: pvlib.temperature +.. autodata:: TEMPERATURE_MODEL_PARAMETERS + :annotation: + +.. currentmodule:: pvlib + +Single diode models +------------------- + +Functions relevant for single diode models. + +.. autosummary:: + :toctree: generated/ + + pvsystem.calcparams_cec + pvsystem.calcparams_desoto + pvsystem.calcparams_pvsyst + pvsystem.i_from_v + pvsystem.singlediode + pvsystem.v_from_i + pvsystem.max_power_point + ivtools.sdm.pvsyst_temperature_coeff + +Low-level functions for solving the single diode equation. + +.. autosummary:: + :toctree: generated/ + + singlediode.estimate_voc + singlediode.bishop88 + singlediode.bishop88_i_from_v + singlediode.bishop88_v_from_i + singlediode.bishop88_mpp + +Functions for fitting diode models + +.. autosummary:: + :toctree: generated/ + + ivtools.sde.fit_sandia_simple + ivtools.sdm.fit_cec_sam + ivtools.sdm.fit_desoto + +Inverter models (DC to AC conversion) +------------------------------------- + +.. autosummary:: + :toctree: generated/ + + pvsystem.PVSystem.get_ac + inverter.sandia + inverter.sandia_multi + inverter.adr + inverter.pvwatts + inverter.pvwatts_multi + +Functions for fitting inverter models + +.. autosummary:: + :toctree: generated/ + + inverter.fit_sandia + + +PV System Models +---------------- + +Sandia array performance model (SAPM) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. autosummary:: + :toctree: generated/ + + pvsystem.sapm + pvsystem.sapm_effective_irradiance + pvsystem.sapm_spectral_loss + inverter.sandia + temperature.sapm_cell + +Pvsyst model +^^^^^^^^^^^^ + +.. autosummary:: + :toctree: generated/ + + temperature.pvsyst_cell + pvsystem.calcparams_pvsyst + pvsystem.singlediode + ivtools.sdm.pvsyst_temperature_coeff + pvsystem.dc_ohms_from_percent + pvsystem.dc_ohmic_losses + +PVWatts model +^^^^^^^^^^^^^ + +.. autosummary:: + :toctree: generated/ + + pvsystem.pvwatts_dc + inverter.pvwatts + pvsystem.pvwatts_losses + +Estimating PV model parameters +------------------------------ + +Functions for fitting single diode models + +.. autosummary:: + :toctree: generated/ + + ivtools.sdm.fit_cec_sam + ivtools.sdm.fit_desoto + ivtools.sdm.fit_pvsyst_sandia + ivtools.sdm.fit_desoto_sandia + +Functions for fitting the single diode equation + +.. autosummary:: + :toctree: generated/ + + ivtools.sde.fit_sandia_simple + +Utilities for working with IV curve data + +.. autosummary:: + :toctree: generated/ + + ivtools.utils.rectify_iv_curve + +Other +----- + +.. autosummary:: + :toctree: generated/ + + pvsystem.retrieve_sam + pvsystem.scale_voltage_current_power diff --git a/docs/sphinx/source/reference/scaling.rst b/docs/sphinx/source/reference/scaling.rst new file mode 100644 index 0000000000..75599282e2 --- /dev/null +++ b/docs/sphinx/source/reference/scaling.rst @@ -0,0 +1,11 @@ +.. currentmodule:: pvlib + +Scaling +======= + +Methods for manipulating irradiance for temporal or spatial considerations + +.. autosummary:: + :toctree: generated/ + + scaling.wvm diff --git a/docs/sphinx/source/reference/solarposition.rst b/docs/sphinx/source/reference/solarposition.rst new file mode 100644 index 0000000000..dbe93d5392 --- /dev/null +++ b/docs/sphinx/source/reference/solarposition.rst @@ -0,0 +1,66 @@ +.. currentmodule:: pvlib + +Solar Position +============== + +Functions and methods for calculating solar position. + +The :py:meth:`location.Location.get_solarposition` method and the +:py:func:`solarposition.get_solarposition` function with default +parameters are fast and accurate. We recommend using these functions +unless you know that you need a different function. + +.. autosummary:: + :toctree: generated/ + + location.Location.get_solarposition + solarposition.get_solarposition + solarposition.spa_python + solarposition.ephemeris + solarposition.pyephem + solarposition.spa_c + + +Additional functions for quantities closely related to solar position. + +.. autosummary:: + :toctree: generated/ + + solarposition.calc_time + solarposition.pyephem_earthsun_distance + solarposition.nrel_earthsun_distance + spa.calculate_deltat + + +Functions for calculating sunrise, sunset and transit times. + +.. autosummary:: + :toctree: generated/ + + location.Location.get_sun_rise_set_transit + solarposition.sun_rise_set_transit_ephem + solarposition.sun_rise_set_transit_spa + solarposition.sun_rise_set_transit_geometric + + +The spa module contains the implementation of the built-in NREL SPA +algorithm. + +.. autosummary:: + :toctree: generated/ + + spa + +Correlations and analytical expressions for low precision solar position +calculations. + +.. autosummary:: + :toctree: generated/ + + solarposition.solar_zenith_analytical + solarposition.solar_azimuth_analytical + solarposition.declination_spencer71 + solarposition.declination_cooper69 + solarposition.equation_of_time_spencer71 + solarposition.equation_of_time_pvcdrom + solarposition.hour_angle diff --git a/docs/sphinx/source/reference/tracking.rst b/docs/sphinx/source/reference/tracking.rst new file mode 100644 index 0000000000..7f2599b6a0 --- /dev/null +++ b/docs/sphinx/source/reference/tracking.rst @@ -0,0 +1,27 @@ +.. currentmodule:: pvlib + +Tracking +======== + +SingleAxisTracker +----------------- + +The :py:class:`~tracking.SingleAxisTracker` inherits from +:py:class:`~pvsystem.PVSystem`. + +.. autosummary:: + :toctree: generated/ + + tracking.SingleAxisTracker + tracking.SingleAxisTracker.singleaxis + tracking.SingleAxisTracker.get_irradiance + +Functions +--------- + +.. autosummary:: + :toctree: generated/ + + tracking.singleaxis + tracking.calc_axis_tilt + tracking.calc_cross_axis_tilt From 6af9b2801c916fad05152813b727538028f3a102 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Wed, 11 Aug 2021 18:14:33 -0600 Subject: [PATCH 10/11] rename auto_examples -> gallery --- docs/sphinx/Makefile | 2 +- docs/sphinx/make.bat | 2 +- docs/sphinx/source/conf.py | 2 +- docs/sphinx/source/index.rst | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/sphinx/Makefile b/docs/sphinx/Makefile index 5259b055ca..6ce74bc014 100644 --- a/docs/sphinx/Makefile +++ b/docs/sphinx/Makefile @@ -49,7 +49,7 @@ help: clean: rm -rf $(BUILDDIR)/* rm -rf source/reference/generated - rm -rf source/auto_examples + rm -rf source/gallery rm -rf source/savefig html: diff --git a/docs/sphinx/make.bat b/docs/sphinx/make.bat index 553a5ae932..555f7d31c0 100644 --- a/docs/sphinx/make.bat +++ b/docs/sphinx/make.bat @@ -18,7 +18,7 @@ if "%1" == "clean" ( 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%\reference\generated >nul 2>&1 - rmdir /q /s %SOURCEDIR%\auto_examples >nul 2>&1 + rmdir /q /s %SOURCEDIR%\gallery >nul 2>&1 rmdir /q /s %SOURCEDIR%\savefig >nul 2>&1 goto end ) diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index 20ce760cbb..e63d561a51 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -350,7 +350,7 @@ def setup(app): # settings for sphinx-gallery sphinx_gallery_conf = { 'examples_dirs': ['../../examples'], # location of gallery scripts - 'gallery_dirs': ['auto_examples'], # location of generated output + 'gallery_dirs': ['gallery'], # location of generated output # sphinx-gallery only shows plots from plot_*.py files by default: # 'filename_pattern': '*.py', diff --git a/docs/sphinx/source/index.rst b/docs/sphinx/source/index.rst index 89353268fc..0314d5ec66 100644 --- a/docs/sphinx/source/index.rst +++ b/docs/sphinx/source/index.rst @@ -91,7 +91,7 @@ Contents :maxdepth: 1 user_guide/index - auto_examples/index + gallery/index reference/index whatsnew contributing From 8c5430a80ae178b09d9419894a0676983da0a0d6 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Wed, 11 Aug 2021 18:20:11 -0600 Subject: [PATCH 11/11] update gitignore --- .gitignore | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 99f36a592a..72b65484d3 100644 --- a/.gitignore +++ b/.gitignore @@ -41,7 +41,7 @@ pvlib/spa_c_files/spa_tester.c # generated documentation docs/sphinx/source/reference/generated docs/sphinx/source/savefig -docs/sphinx/source/auto_examples +docs/sphinx/source/gallery # Installer logs pip-log.txt