DOC: Add plot options API examples for Imviz

[pllim]

Description

This pull request is to add user facing examples for plot options API for Imviz so users can operate on multiple images at once.

Fixes #1477

Change log entry

• Is a change log needed? If yes, is it added to CHANGES.rst? If you want to avoid merge conflicts,
  list the proposed change log here for review and add to CHANGES.rst before merge. If no, maintainer
  should add a no-changelog-entry-needed label.

Checklist for package maintainer(s)

This checklist is meant to remind the package maintainer(s) who will review this pull request of some common things to look for. This list is not exhaustive.

• Are two approvals required? Branch protection rule does not check for the second approval. If a second approval is not necessary, please apply the trivial label.
• Do the proposed changes actually accomplish desired goals? Also manually run the affected example notebooks, if necessary.
• Do the proposed changes follow the STScI Style Guides?
• Are tests added/updated as required? If so, do they follow the STScI Style Guides?
• Are docs added/updated as required? If so, do they follow the STScI Style Guides?
• Did the CI pass? If not, are the failures related?
• Is a milestone set?
• After merge, any internal documentations need updating (e.g., JIRA, Innerspace)?

[pllim]

@rosteen , glue vs Glue is back.

[pllim]

Not sure why change log check is cancelled but this PR does not need one. 🤷

[codecov]

Codecov Report

Base: 87.16% // Head: 87.27% // Increases project coverage by +0.10% 🎉

Coverage data is based on head (2408431) compared to base (3df8b3b).
Patch has no changes to coverable lines.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1704      +/-   ##
==========================================
+ Coverage   87.16%   87.27%   +0.10%     
==========================================
  Files          95       95              
  Lines        9914    10097     +183     
==========================================
+ Hits         8642     8812     +170     
- Misses       1272     1285      +13     

Impacted Files	Coverage Δ
...onfigs/mosviz/plugins/slit_overlay/slit_overlay.py	71.05% <0.00%> (-16.28%)	⬇️
jdaviz/configs/specviz2d/plugins/parsers.py	33.33% <0.00%> (-2.16%)	⬇️
jdaviz/core/template_mixin.py	92.47% <0.00%> (-0.24%)	⬇️
jdaviz/configs/imviz/plugins/parsers.py	100.00% <0.00%> (ø)
jdaviz/configs/specviz/plugins/parsers.py	89.02% <0.00%> (ø)
jdaviz/configs/specviz/plugins/viewers.py	84.23% <0.00%> (ø)
...daviz/configs/default/plugins/collapse/collapse.py	100.00% <0.00%> (ø)
...figs/default/plugins/line_lists/line_list_mixin.py	87.17% <0.00%> (ø)
...igs/specviz/plugins/line_analysis/line_analysis.py	98.03% <0.00%> (+<0.01%)	⬆️
jdaviz/configs/imviz/helper.py	96.68% <0.00%> (+0.01%)	⬆️
... and 19 more

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

[kecnry]

If the goal here is to provide examples for both the astrowidgets and plugin APIs, I think the user might need a little more context (without getting into development details) for the distinction between the two so they don't get confused.... but that is a fine line to try to walk.

How would you feel about moving the plot options examples into a "From the API" section in the plugin docs and link to it from here? This page could then show the astrowidgets API only and include a link that says something like "alternatively, these options can be set from the plot options plugin or its API, which provides the ability to set options across multiple selected viewers/layers simultaneously"?

[kecnry]

technically setting the preset to 'Custom' isn't necessary, but I agree its nice to be verbose here to show the user what is happening.

[duytnguyendtn]

I agree; I usually like examples where they show "a little extra"

[pllim]

How would you feel about moving the plot options examples into a "From the API" section

I think this is a better question for @camipacifici or @hcferguson . They would be reading the doc, not me.

[rosteen]

Looks good to me, thanks.

[duytnguyendtn]

A small few nitpicks if you wanted to entertain the suggestion. Otherwise, I think it reads fine! Thanks :)

[kecnry]

(I still think it would be worthwhile to separate the different APIs and make the distinction more clear, but looks like there are two approvals without that, so we could always reconsider if it seems to cause any user-confusion)

[pllim]

@kecnry , I opened a new issue at #1732 as a follow-up.

Thanks, all!