DM-46178: Documentation fixes for new query system

[kfindeisen]

This PR addresses various documentation issues that came up while working on lsst-dm/prompt_processing#249.

Checklist

• ran Jenkins
• added a release note for user-visible changes to doc/changes
• (if changing dimensions.yaml) make a copy of dimensions.yaml in configs/old_dimensions

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 89.47%. Comparing base (440f5ac) to head (c2c0ee8).
Report is 7 commits behind head on main.

✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1149   +/-   ##
=======================================
  Coverage   89.47%   89.47%           
=======================================
  Files         366      366           
  Lines       49115    49115           
  Branches     5955     5955           
=======================================
  Hits        43944    43944           
  Misses       3753     3753           
  Partials     1418     1418           

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

[TallJimbo]

For future reference, I think I prefer Sphinx's relative-name syntax (leading . for each parent level to move up) to qualifying everything with absolute module names, and I don't consider being able to reference a name in the exact same package without qualification to be lucky; it's correctly concise and just about the only part of Sphinx's name resolution rules/syntax that works like it should.

But this is a big improvement over the previous situation that you didn't have to contribute to get your work done, so I'm certainly not going to ask you to redo it here!

This might also be a good time to see if @timj, @dhirving, and @andy-slac have different opinions on how to handle namespaced references in docs.

[kfindeisen]

For future reference, I think I prefer Sphinx's relative-name syntax (leading . for each parent level to move up) to qualifying everything with absolute module names, and I don't consider being able to reference a name in the exact same package without qualification to be lucky; it's correctly concise and just about the only part of Sphinx's name resolution rules/syntax that works like it should.

The problem is that this is not a matter of "preference" -- the Sphinx links simply do not, and cannot, work the way you seem to think they do. The Sphinx parser does not have access to the source code, and evaluates relative links based on the package in which the component is documented. If a component is lifted into a higher-level namespace (a decision that often happens independently of writing the docstrings), links are relative to that. If it is documented in both high-level and low-level namespaces (as is common in MW), then any relative links will work in at most one of those places.

So I stand by my statement that the working links were such only through luck: many, if not most, of the links I fixed look like the writer assumed that the referenced component was in the same package when, in the context of the documentation, it wasn't.

[TallJimbo]

I'm aware the syntax and lookup behavior is not the same as Python's actual import system (which is mind-bogglingly frustrating), but there is a relative syntax that does work, if you take into account where things are documented rather than where they are declared.