link the imviz markers docs to the catalog docs so that the add_markers functionality is clear

[eteq]

For context, I'm starting from a workflow where I was happy using the Imviz.default_viewer.add_markers(...) API. I was trying to replicate this using the new plugins API. I read the docs and perused a live session with the markers plugin API but gave up add assumed for some reason this wasn't supported.

I asked @camipacifici about this and got clarification that the path I should have followed was to use the catalog search plugin to upload a catalog, and then view that in with the markers plugin. This is a reasonable workflow (it's slightly more annoying than add_markers, but not the end of the world), but I couldn't figure that out from the public API info available to me. So I suggest two things:

1. Add some notes to the https://jdaviz.readthedocs.io/en/latest/imviz/plugins.html#markers section of the docs pointing the user to the catalog section as being where you go to add markers from an existing catalog, and
2. try to get this in the API docs somewhere as well so that someone using just tab-completion might see the pointer as well

[kecnry]

was to use the catalog search plugin to upload a catalog, and then view that in with the markers plugin

Can you or @camipacifici clarify here - does catalogs alone not do what you need? The user API for that plugin hasn't been made public yet because of planned major changes, but the UI should allow importing a catalog file and I'm hopeful that the API hints would otherwise point you to how to do what you need 🤞

[eteq]

It might be I don't understand the scope of catalog API... but my confusion here stems from the fact that when I want to put "marks" on the image, it seems natural to go to the marker plugin... and indeed that's where I go to place markers from scratch, but if, say, I want to re-load some marks I made before (exactly what I was trying to do), it's confusing to have to know that I should use a different plugin and have nothing to point me there. Especially so given that most other image viewers (i.e. what astrowidgets was based on), don't separate these out as two spearate concepts.

Note also that what I'm trying to do here is not the same as "searching for a catalog", in that the "catalog" is some random astropy table that I may have produced by hand or via some custom algorithm or whatever. It's still a "catalog" if we define catalog as anything that has x/y or ra/dec or whatever, but it's not a catalog that exists anywhere other than memory on my specific machine. Not sure if that matters or not, but it might clarify things, @kecnry ?

[kecnry]

Ok, thanks. We had larger plans for the Markers plugin that motivated that name, as well as discussions about possibly merging functionality with catalogs, etc, but that was never completed and is made more complicated now by other advanced catalog workflows in progress. I agree with your first point to add some note in the markers docs that basically explains the current scope of the plugin (effectively just a log of mouseover information) and redirect users to catalogs for this workflow, since that may not be intuitive otherwise. I think the "and then view that in with the markers plugin" is what confused me - as long as we're not suggesting some sort of mixed workflow with both plugins, then I think we're on the same page.

As for your second point (try to get this in the API docs somewhere as well so that someone using just tab-completion might see the pointer as well) - I think that will hopefully happen naturally when we make the catalogs API officially public. Maybe we should prioritize trying to do that sooner rather than waiting for the entire source-catalog logic to be in place first.