class methods do not have doc pages

[wholmgren]

Describe the bug
Many PVSystem class methods do not have doc pages.

To Reproduce
Go to the PVSystem doc page, notice that many methods don't have links.

Versions:

• pvlib.__version__: 0.8.0b0

A of couple of approaches to consider:

Might try adding sphinx 3.1 :recursive: option here. There's some compatibility reason we're on an older version of sphinx (maybe a sphinx gallery issue?).

Modify the sphinx autosummary class template.

Manually document the methods in api.rst. We should be doing this anyways.

[veronicaguo]

Hi @wholmgren , I'd be happy to take a stab at this.

[wholmgren]

@veronicaguo thanks! No preference here on the approach - could be one of the ideas in my initial comment or could be something else.

[kandersolar]

There's some compatibility reason we're on an older version of sphinx (maybe a sphinx gallery issue?).

See #911 (comment), it was because of poor formatting in the sphinx 2.x html output and nuisance warnings. Looks like a lot of development has gone into Sphinx since February, so if we want to start using sphinx features added after 1.8.5, it's probably worth trying out the current release again!

[veronicaguo]

So I tried a few things...

• Sphinx 3.1.2 seems to work well now. It doesn't output any warnings, and the format looks very much like the existing docs except tighter line spacing for class methods descriptions.
• Adding :recursive to api.rst doesn't create the links, but adding the following after .. autosummary:: in methods block in class template does work.

        :toctree:
        :recursive:
  

  • The downside is that it generates a full toctree for each class, so will create duplicate links for methods that are grouped already, like PVSystem.get_aoi.
• Manually document the methods in api.rst works as expected, consistent with the current doc structure. Need to add methods in SingleAxisTracker class too.

wondering what's the preference here between the two approaches, and if we want to upgrade sphinx to the latest release.

[cwhanse]

Duplicate links don't bother me. If someone is looking up a method, they may be asking "what can I do with PVSystem" or they could be asking "what are the options for the _____ model"?

If I understand correct, we either add :recursive: where a Class appears in api.rst, or, we add an line for every class method. Either one would be maintainable for those who need a pattern to follow.