Create FAQ page in sphinx User Guide

README.md

@@ -93,8 +93,8 @@ but operate independently of it.
 Documentation
 =============
 
-Full documentation can be found at [readthedocs](http://pvlib-python.readthedocs.io/en/stable/).
-
+Full documentation can be found at [readthedocs](http://pvlib-python.readthedocs.io/en/stable/),
+including an [FAQ](http://pvlib-python.readthedocs.io/en/stable/user_guide/faq.html) page.
 
 Installation
 ============

docs/examples/README.rst

@@ -1,3 +1,5 @@
+.. _example_gallery:
+
 Example Gallery
 ===============
 

docs/sphinx/source/user_guide/faq.rst

@@ -0,0 +1,140 @@
+.. _faq:
+
+Frequently Asked Questions
+==========================
+
+General Questions
+*****************
+
+What is pvlib?
+--------------
+
+pvlib is a free and open-source python software library for modeling
+the electrical performance of solar photovoltaic (PV) systems.  It provides
+implementations of scientific models for many topics relevant for PV modeling.
+
+For additional details about the project, see :ref:`package_overview`.
+For examples of using pvlib, see :ref:`example_gallery`.
+
+
+How does pvlib compare to other PV modeling tools like PVsyst or SAM?
+---------------------------------------------------------------------
+
+pvlib is similar to tools like PVsyst and SAM in that it can be used
+for "weather-to-power" modeling to model system energy production
+based on system configuration and a weather dataset.  However, pvlib
+is also very different in that you use pvlib via python code instead
+of via a GUI, which makes pvlib ideal for automating tasks.  pvlib
+is also more of a toolbox or a framework to use
+to build your own modeling process (although some pre-built workflows
+are available as well).
+
+
+Usage Questions
+***************
+
+All I have is GHI, how do I get to POA?
+---------------------------------------
+
+Going from GHI to plane of array (POA) irradiance is a two-step process. 
+The first step is to
+use a decomposition model (also called a separation model) to estimate the
+DNI and DHI corresponding to your GHI.  For a list of decomposition
+models available in pvlib, see :ref:`dniestmodels`.
+
+The second step is to transpose those estimated DNI and DHI components into
+POA components.  This is most easily done with the
+:py:func:`pvlib.irradiance.get_total_irradiance` function.
+
+
+Where can I get irradiance data for my simulation?
+--------------------------------------------------
+
+pvlib has a module called iotools which has several functions for
+retrieving irradiance data as well as reading standard file formats
+such as EPW, TMY2, and TMY3. For free irradiance data, you may
+consider NREL's NSRDB which can be accessed using the
+:py:func:`pvlib.iotools.get_psm3` function and is available for
+North America. For Europe and Africa, you may consider looking into
+CAMS (:py:func:`pvlib.iotools.get_cams`).
+PVGIS (:py:func:`pvlib.iotools.get_pvgis_hourly`) is another option, which
+provides irradiance from several different databases with near global coverage.
+pvlib also has functions for accessing a plethora of ground-measured
+irradiance datasets, including the BSRN, SURFRAD, SRML, and NREL's MIDC.
+
+
+Can I use PVsyst (PAN/OND) files with pvlib?
+--------------------------------------------
+
+Currently, pvlib does not have the ability to import any PVsyst file formats.
+Certain formats of particular interest (e.g. PAN files) may be added in a future
+version.  Until then, these Google Group threads
+(`one <https://groups.google.com/g/pvlib-python/c/PDDic0SS6ao/m/Z-WKj7C6BwAJ>`_
+and `two <https://groups.google.com/g/pvlib-python/c/b1mf4Y1qHBY/m/tK2FBCJyBgAJ>`_)
+may be useful for some users.
+
+
+Why don't my simulation results make sense? 
+-------------------------------------------
+
+pvlib does not prevent you from using models improperly and generating
+invalid results.  It is on you as the user to understand the models you
+are using and to supply appropriate, correctly-formatted data.  One modeling error that beginners sometimes
+make is improper time zone localization. Calculating solar
+positions is often the first step of a modeling process
+and this step relies on timestamps being localized to the correct time zone.
+A telltale sign of improper time zones is a time shift between solar
+position and the irradiance data (for example, ``solar_elevation``
+peaks at a different time from clear-sky ``ghi``).
+For more information on handling timezone correctly, see :ref:`timetimezones`.
+
+More generally, inspecting the simulation results visually is a good first
+step when investigating strange results.
+Matplotlib and pandas have very powerful plotting capabilities that are great
+for tracking down where things went wrong in a modeling process.  Try plotting
+a few days of intermediate time series results in a single plot, looking for
+inconsistencies like nonzero irradiance when the sun is below the horizon.
+This will give you a clue of where to look for errors in your code.
+
+
+I got a warning like ``RuntimeWarning: invalid value encountered in arccos``, what does it mean?
+------------------------------------------------------------------------------------------------
+
+It is fairly common to use pvlib models in conditions where they are not
+applicable, for example attempting to calculate an IV curve at night.
+In such cases the model failure doesn't really matter (nighttime values are
+irrelevant), but the numerical packages that pvlib is built on
+(e.g. `numpy <https://numpy.org>`_) emit warnings complaining about
+`invalid value`, `divide by zero`, etc.  In these cases the warnings can
+often be ignored without issue.
+
+However, that's not always the case: sometimes these warnings are caused
+by an error in your code, for example by giving a function inappropriate inputs.
+So, these warnings don't necessarily indicate a problem, but you shouldn't
+get in the habit of immediately discounting them either.
+
+
+I got an error like ``X has no attribute Y``, what does it mean?
+----------------------------------------------------------------
+
+If you see a function in the pvlib documentation that doesn't seem to exist
+in your pvlib installation, the documentation is likely for a different version
+of pvlib.  You can check your installed pvlib version by running
+``print(pvlib.__version__)`` in python.  To switch documentation versions, use
+the `v:` version switcher widget in the bottom right corner of this page.
+
+You can also upgrade your installed pvlib to the latest compatible version
+with ``pip install -U pvlib``, but be sure to check the :ref:`whatsnew`
+page to see the differences between versions.
+
+
+The CEC table doesn't include my module or inverter, what should I do?
+----------------------------------------------------------------------
+
+The CEC tables for module and inverter parameters included in pvlib are periodically
+copied from `SAM <https://github.com/NREL/SAM/tree/develop/deploy/libraries>`_,
+so you can check the tables there for more up-to-date tables.
+
+For modules, if even the SAM files don't include the module you're looking for
+either, you can calculate CEC module model parameters from
+datasheet information using :py:func:`pvlib.ivtools.sdm.fit_cec_sam`.

docs/sphinx/source/user_guide/index.rst

@@ -18,3 +18,4 @@ User Guide
    comparison_pvlib_matlab
    variables_style_rules
    singlediode
+   faq

docs/sphinx/source/whatsnew/v0.9.4.rst

@@ -33,6 +33,7 @@ Testing
 
 Documentation
 ~~~~~~~~~~~~~
+* Added an FAQ page to the docs: :ref:`faq`. (:issue:`1546`, :pull:`1549`)
 * Fixed equation in :py:func:`pvlib.iam.martin_ruiz` docstring (:issue:`1561`, :pull:`1599`)
 
 Benchmarking