DOC: fix napoleon, render sphinx docs right

[mikofski]

pvlib python pull request guidelines

Thank you for your contribution to pvlib python! You may delete all of these instructions except for the list below.

You may submit a pull request with your code at any stage of completion.

The following items must be addressed before the code can be merged. Please don't hesitate to ask for help if you're unsure of how to accomplish any of the items below:

• Closes issue Read The Docs not rendering API arguments : types correctly #690
• I am familiar with the contributing guidelines.
• Fully tested. Added and/or modified tests to ensure correct behavior for all reasonable inputs. Tests (usually) must pass on the TravisCI and Appveyor testing services.
• Updates entries to docs/sphinx/source/api.rst for API changes.
• Adds description and name entries in the appropriate docs/sphinx/source/whatsnew file for all changes.
• Code quality and style is sufficient. Passes LGTM and SticklerCI checks.
• New code is fully documented. Includes sphinx/numpydoc compliant docstrings and comments in the code where necessary.
• Pull request is nearly complete and ready for detailed review.

Brief description of the problem and proposed solution (if not already fully described in the issue linked to above):

• add napoleon extension to sphinx source conf.py
• fix see also in solar_zenith_analytical

[wholmgren]

Thanks Mark. My understanding is that we should use either the napoleon extension or the numpydoc extension, but not both. I googled around a bit for pros/cons of napoleon with numpydoc formatting vs. just using numpydoc. I didn't find anything conclusive. It seems that switching from numpydoc to napoleon is trivial for some projects and difficult for others. We'd need to thoroughly check the build to make sure that all pages render correctly.

[mikofski]

new docs as rendered are here

[wholmgren]

Overall, I prefer the napoleon formatting. I also like that it links to the allowed types. I wonder if there's a way to link to custom definitions for "numeric" and "array-like" (not required here, just thinking).

I've listed a handful of issues below. Many of these are also issues in the numpydoc build, but the differences in formatting have made them breaking issues instead of nice to have fixes.

• Location.get_solarposition param kwargs
• new line needed after return type in solar_zenith_analytical
• Location.get_clearsky kwargs spec is not sensible with napoleon. It's just poorly formatted with numpydoc. See PVSystem.get_irradiance for working kwargs spec.
• sapm returns section
• SingleAxisTracker params not rendered right.
• ModelChain.prepare_inputs Assigns attributes list spilling to next line makes the section too confusing. Move it to notes?
• bifacial parameters not rendered

Things that are entirely broken in both and not required here:

• SingleAxisTracker.singleaxis

[mikofski]

• Location.get_solarposition param kwargs
  just needed a newline and tab after kwargs
  

• new line needed after return type in solar_zenith_analytical
  
  FYI: this is the expected rtype behavior for sphinx, setting napoleon_use_rtype = False changes this to:
  

• Location.get_clearsky kwargs spec is not sensible with napoleon.
  Just needs newline and tab after kwargs
  

• sapm returns section
  How do you want this to look? Separating rtype is the default Sphinx expected. I'll try napoleon_use_rtype = False maybe it looks better:
  

• SingleAxisTracker params not rendered right.
  It was missing the Parameters heading before the arguments list

• ModelChain.prepare_inputs Assigns attributes list spilling to next line makes the section too confusing. Move it to notes?

• bifacial parameters not rendered

• SingleAxisTracker.singleaxis

[wholmgren]

FYI: this is the expected rtype behavior for sphinx, setting napoleon_use_rtype = False changes this to:

ah, I prefer the behavior when set to False. Your preference?

[mikofski]

It appears that the __init__ method has always been listed in the documentation, see v0.6.0, but I can't figure out how to get rid of it, things I've tried, but failed:

• get rid of numpydoc extensions
• set numpydoc directive numpydoc_show_class_members to false
• set napoleon_include_init_with_doc to false
• set napoleon_include_special_with_doc to false
• set napoleon_include_private_with_doc to false
• delete source/generated folder
• hard cache reset the browser
• add extra newline after Parameters section
  I give up :(

[mikofski]

napolean directives I did not use:

# napoleon_google_docstring = False
# napoleon_use_param = False
# napoleon_use_ivar = True
# napoleon_include_init_with_doc = False
# napoleon_include_private_with_doc = False
# napoleon_include_special_with_doc = False

[mikofski]

Make sure to reset browser cache before checking rendered docs

[wholmgren]

I like it! Minor comments and line too long errors...

[wholmgren]

Thanks Mark!