Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

Sphinx emits lots of warnings when building docs #911

Copy link
Copy link
Closed
@kandersolar

Description

@kandersolar
Issue body actions

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.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions

      Morty Proxy This is a proxified and sanitized view of the page, visit original site.