Docstring for ModelChainResult

[cwhanse]

• Closes Improve documentation of ModelChainResult class #1126
• I am familiar with the contributing guidelines
• Tests added
• Updates entries to docs/sphinx/source/api.rst for API changes.
• Adds description and name entries in the appropriate "what's new" file in docs/sphinx/source/whatsnew for all changes. Includes link to the GitHub Issue with :issue:`num` or this Pull Request with :pull:`num`. Includes contributor name and/or GitHub username (link with :ghuser:`user`).
• New code is fully documented. Includes numpydoc compliant docstrings, examples, and comments where necessary.
• Pull request is nearly complete and ready for detailed review.
• Maintainer: Appropriate GitHub Labels and Milestone are assigned to the Pull Request and linked Issue.

[kandersolar]

PerArray makes an undesirable appearance in the list of attributes (link); should we rename it to _PerArray?

[kandersolar]

Suggested change

	:py:meth:`~pvlib.location.get_airmass` for details."""
	:py:meth:`~pvlib.location.Location.get_airmass` for details."""

[wholmgren]

this is great!

[wholmgren]

never a tuple

[wholmgren]

never a tuple

[wholmgren]

PerArray makes an undesirable appearance in the list of attributes (link); should we rename it to _PerArray?

type linters complain about the line _T = TypeVar('T') - they want it to be T = TypeVar('T'). I assume that would mean the generic type var would also show up in the docs. So maybe there is a way to exclude the attributes? Or move them to the module scope?

[kandersolar]

PerArray makes an undesirable appearance in the list of attributes (link); should we rename it to _PerArray?

type linters complain about the line _T = TypeVar('T') - they want it to be T = TypeVar('T'). I assume that would mean the generic type var would also show up in the docs. So maybe there is a way to exclude the attributes? Or move them to the module scope?

Moving to module scope seems to solve the problem, although I did not get mypy's opinion about it. I looked around a bit for how other packages document dataclasses and came up mostly short -- this is the only example I found, which uses the standard approach of docstring sections: https://github.com/scipy/scipy/blob/701ffcc8a6f04509d115aac5e5681c538b5265a2/scipy/stats/_relative_risk.py#L21

[wholmgren]

I'd also like to see the type hints removed from the class signature. Nobody is going to directly instantiate this class, but all that text could be distracting/intimidating. My reading is that we just need to add autodoc_typehints = 'none' to conf.py (see sphinx docs) but that isn't working for me. Might be specific to the dataclass init - maybe find a way to skip the signature entirely?

[cwhanse]

I'd also like to see the type hints removed from the class signature. Nobody is going to directly instantiate this class, but all that text could be distracting/intimidating. My reading is that we just need to add autodoc_typehints = 'none' to conf.py (see sphinx docs) but that isn't working for me. Might be specific to the dataclass init - maybe find a way to skip the signature entirely?

I agree that text is distracting, but I have no idea how to suppress it either.

[cwhanse]

@wholmgren hints to controlling a dataclass docstring here?

[wholmgren]

Let's not worry about the signature in this pr.

[wholmgren]

No underscore on either of these. Type variables should be public so other libraries that build on pvlib can inspect them and benefit from them.

[wholmgren]

merge when green.