Automate autosummary documentation (WIP)

[JoelPasvolsky]

Main points:

• Prevents missed functions. I see this as the main motivation (every module has a couple of functions that were missed).
• Is not applied by default: one must manually apply the new templates so any application is verified
• Sphinx's Jinja templates do not change much and are not hard to update if there are changes in the future
• A disadvantage is the extra clickthrough but I think that is balanced by having the summary with one-sentence descriptions that enables a quick scan of multiple functions.

This is an incomplete PR to get early reviews on the mechanism and if we want to proceed. If yes, I'll improve it before the final PR for review. So expect some rough edges and leave those for the final PR. I'm also opening another for a wider picture: dwave-optimization.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.93%. Comparing base (c1f17f6) to head (9a44ff5).

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #585      +/-   ##
==========================================
- Coverage   89.38%   86.93%   -2.46%     
==========================================
  Files          22       22              
  Lines        1997     1997              
==========================================
- Hits         1785     1736      -49     
- Misses        212      261      +49     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[arcondello]

I am a bit concerned about the maintenance of the template files. If/when we find some edge case then we'll have to update them in each repo. But probably that is net less maintenance than keeping all of the various autosummarys up to date. So seems reasonable to me

[thisac]

Looks and feels much better IMO.

I am a bit concerned about the maintenance of the template files. If/when we find some edge case then we'll have to update them in each repo.

I was also thinking about this. Although, I suppose the SDK templates would be the only ones needed for the published docs (no?), not to say that we shouldn't keep the local builds working as well.

[arcondello]

I use the local builds myself frequently to test docs. So I think it needs to function in each individual repo, which means copying this file everywhere.

I'll also say that IMO a better approach would be to modify autoclass and automodule etc. The advantage there is we could choose to do it in line rather than creating a new nested file each time. I understand that might be more complex though.

I also think we could use vanilla autoclass and automodule for now. We would lose the nice TOCs at the top but we would be able to keep the autogeneration. That might be an intermediate step between what we have and this. One that would allow us to get more comfy with the templates.

Also, we discovered in the dwave-optimization PR that this approach doesn't handle aliases. Which seems like it may be a problem. 🤷

[JoelPasvolsky]

I also think we could use vanilla autoclass and automodule for now. We would lose the nice TOCs at the top but we would be able to keep the autogeneration.

Note that if you try the autosummary directive at the module or class levels with the existing templates you do not get documentation for the underlying properties & methods. (At the module level you also get our current module filenames as the links, which is not ideal.)

Without some updates to templates or code (changing the sphinx autosummary code is not simple at all) the best we can do, as far as I can tell, is to use the default autoclass directive with the :members: option. That gets us all the methods & properties but where there are many it is less easy to scan through. Please see Samplers page and Composites page rendered HTML examples (and compare to this PR's samplers page).

Let me know what you think. I do think our top priority is missed functions. If the rendering shown above is acceptable as a automated-docs halfhouse, might be worth a PR for the upcoming SDK.