Sphinx emits lots of warnings when building docs

Sphinx currently emits a few types of warnings when building the docs, none are really a big deal but it clutters the output and makes #909 less effective. I’ll open a PR shortly to address:

Docutils warning

/usr/share/miniconda/envs/test_env/lib/python3.8/site-packages/sphinx/util/nodes.py:94: FutureWarning: 
   The iterable returned by Node.traverse()
   will become an iterator instead of a list in Docutils > 0.16.

I’m not 100% sure what this one is, but I assume it is related to the newest version of docutils deprecating something and sphinx hasn’t caught up yet. example

I’ll play around with pinning the docutils version and see if that fixes it.

Improper RST in gallery example

The I-V curve example generates WARNING: Title underline too short. because the page title got updated without extending the underline (my bad). Easy fix. link

First-line references

The first lines of docstrings get orphaned when they are copied into the API Reference docs page and Sphinx emits a bunch of warnings about it: example

There were a few votes in #909 to remove references from first lines of docstrings to prevent these warnings. If nobody objects, I’ll move references into the second part of the docstring, for instance:

Current:

def nrel_earthsun_distance(time, how='numpy', delta_t=67.0, numthreads=4):
    """
    Calculates the distance from the earth to the sun using the
    NREL SPA algorithm described in [1]_.

    Parameters
    ----------
    time : pandas.DatetimeIndex

New:

def nrel_earthsun_distance(time, how='numpy', delta_t=67.0, numthreads=4):
    """
    Calculates the distance from the earth to the sun using the
    NREL SPA algorithm.

    The details of the NREL SPA algorithm are described in [1]_.

    Parameters
    ----------
    time : pandas.DatetimeIndex

This is related to #837 but that’s a much bigger job and I’d rather not tackle it right now.

[mikofski]

FYI: I fixed the 1st line reference issue for losses.py in #910

https://github.com/pvlib/pvlib-python/blob/64ec94d811a6608842151b6b519f845f7ea9613e/pvlib/losses.py#L16-L21

https://github.com/pvlib/pvlib-python/blob/64ec94d811a6608842151b6b519f845f7ea9613e/pvlib/losses.py#L103-L111

and I also noticed that they show up for gallery examples in the tooltip popup, so I removed it from the Kimber soiling example here too:

https://github.com/pvlib/pvlib-python/blob/64ec94d811a6608842151b6b519f845f7ea9613e/docs/examples/plot_greensboro_kimber_soiling.py#L1-L30

[kanderso-nrel]

I’d say let’s do option 2 for now and revisit after sphinx_rtd_theme cuts a new release. From reading through their issue log, it seems like the next release is focused on improving support for sphinx 2+ anyway so it should be a good time to bump our sphinx version.