docs: Drop modifierclass and improve autosummary

[kratsg]

Pull Request Description

We've been a bit held back by the terrible modifierclass.rst I wrote a long time ago and it's been making some of the documentation a bit worse for the wear in general. This PR will migrate some portion of this into the autosummary extension instead under class.rst to only impact the autoclass parts.

Fixes #761, fixes #1339.

Checklist Before Requesting Reviewer

• Tests are passing
• "WIP" removed from the title of the pull request
• Selected an Assignee for the PR to be responsible for the log summary

Before Merging

For the PR Assignees:

• Summarize commit messages into a comprehensive review of the PR

* Improve autosummary documentation for classes, modules, functions and drop modifierclass template
* Split up inference into sub-sub-sections for clearer organization
* Remove method/function signatures from everything on the top-level API page

[kratsg]

Notes to self:

• need to understand what the :nosignatures: is actually doing here, but we likely don't need it...
• get the functions working as well (should not be using the full name if we don't have to)
• fix up github links in a smart way if possible

[codecov]

Codecov Report

Merging #1338 (01838e8) into master (8de7566) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #1338   +/-   ##
=======================================
  Coverage   97.50%   97.50%           
=======================================
  Files          63       63           
  Lines        3760     3760           
  Branches      538      538           
=======================================
  Hits         3666     3666           
  Misses         55       55           
  Partials       39       39           

Flag	Coverage Δ
unittests	97.50% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
src/pyhf/optimize/opt_minuit.py	100.00% <ø> (ø)
src/pyhf/optimize/opt_scipy.py	100.00% <ø> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 8de7566...01838e8. Read the comment docs.

[matthewfeickert]

@kratsg overall I really like these changes. They make things much nicer IMO and I really like in general how the Infer docs are sectioned out now.

I'm not sure if it can be fixed here, but the "Minimizer Options" aren't being displayed correctly for the optimizer _minimize methods.

https://pyhf--1338.org.readthedocs.build/en/1338/_generated/pyhf.optimize.opt_scipy.scipy_optimizer.html

we've never been able to see the _minimize methods before, so it isn't surprising they might not look perfect.

[matthewfeickert]

• fix up github links in a smart way if possible

What is the problem with the GitHub links? I think I missed this.

[kratsg]

What is the problem with the GitHub links? I think I missed this.

the Edit on GitHub etc have been broken for a while -- and it seems like nobody really uses them, so I'm dropping them by default.

[matthewfeickert]

the Edit on GitHub etc have been broken for a while -- and it seems like nobody really uses them, so I'm dropping them by default.

I had to go look and see what these buttons even were...so I think that's a very safe bet.

[matthewfeickert]

@kratsg I'll approve this now and I'll let you decide if we worry about the "Minimizer Options" render here or make a new Issue for it for another later PR.

[kratsg]

@kratsg I'll approve this now and I'll let you decide if we worry about the "Minimizer Options" render here or make a new Issue for it for another later PR.

Do you know how to fix the render? Particularly, it should just be specifying the additional keyword arguments that go into options in that signature.

[kratsg]

I'm not sure if it can be fixed here, but the "Minimizer Options" aren't being displayed correctly for the optimizer _minimize methods.

#1339 will handle the fix of the docstring.

[matthewfeickert]

Do you know how to fix the render? Particularly, it should just be specifying the additional keyword arguments that go into options in that signature.

@kratsg Can you take a look at what I have now? I turned them into bulleted lists.

[matthewfeickert]

#1339 will handle the fix of the docstring.

Oh. Seems we just missed each other. Do you want me to revert this and make a new PR?

[kratsg]

Oh. Seems we just missed each other. Do you want me to revert this and make a new PR?

Looks good. We'll close both issues in this PR and move on.

[matthewfeickert]

Looks good. We'll close both issues in this PR and move on.

okay sounds good. Let me push one more style fix.