From 6c251463e372db7585c936e958205c96d22e3f12 Mon Sep 17 00:00:00 2001
From: "David H. Irving" <david.irving@noirlab.edu>
Date: Wed, 16 Oct 2024 16:07:01 -0700
Subject: [PATCH] Include advanced query system objects in docs

`Butler.query` has been public for a while, but the documentation for the `Query` object it returns was not included in the documentation.

This change pulls in the user-facing portions of the interface without any of the internal objects.  (The internal objects are sometimes referenced from constructors, but those constructors are documented as "do not use".)
---
 doc/lsst.daf.butler/index.rst                 | 22 +++++++++++++++++++
 python/lsst/daf/butler/queries/_query.py      |  3 ++-
 .../lsst/daf/butler/queries/tree/__init__.py  |  1 -
 3 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/doc/lsst.daf.butler/index.rst b/doc/lsst.daf.butler/index.rst
index 7c20d4a538..3b71642a0e 100644
--- a/doc/lsst.daf.butler/index.rst
+++ b/doc/lsst.daf.butler/index.rst
@@ -104,6 +104,17 @@ Python API reference
    :no-inherited-members:
    :skip: RegistryConfig
 
+Advanced query system
+---------------------
+
+.. automodapi:: lsst.daf.butler.queries
+   :headings: ^"
+   :no-main-docstr:
+
+.. automodapi:: lsst.daf.butler.queries.expression_factory
+   :headings: ^"
+   :no-main-docstr:
+
 Example datastores
 ------------------
 
@@ -173,6 +184,17 @@ Datastore utilities
    :headings: ^"
    :skip: Datastore
 
+Advanced query system internals
+-------------------------------
+
+.. automodapi:: lsst.daf.butler.queries.tree
+   :no-main-docstr:
+   :no-inherited-members:
+   :headings: ^"
+   :include: Predicate
+   :skip: DataCoordinateUploadKey
+   :skip: MaterializationKey
+
 Registry utilities and interfaces
 ---------------------------------
 
diff --git a/python/lsst/daf/butler/queries/_query.py b/python/lsst/daf/butler/queries/_query.py
index bb57a5fb15..32049dad0d 100644
--- a/python/lsst/daf/butler/queries/_query.py
+++ b/python/lsst/daf/butler/queries/_query.py
@@ -82,7 +82,7 @@ class Query(QueryBase):
     Notes
     -----
     `Query` objects should never be constructed directly by users; use
-    `Butler._query` instead.
+    `Butler.query` instead.
 
     A `Query` object represents the first stage of query construction, in which
     constraints and joins are defined (roughly corresponding to the WHERE and
@@ -135,6 +135,7 @@ def constraint_dimensions(self) -> DimensionGroup:
     @property
     def expression_factory(self) -> ExpressionFactory:
         """A factory for column expressions using overloaded operators.
+        (`~lsst.daf.butler.queries.expression_factory.ExpressionFactory`).
 
         Notes
         -----
diff --git a/python/lsst/daf/butler/queries/tree/__init__.py b/python/lsst/daf/butler/queries/tree/__init__.py
index e320695f62..f59363d407 100644
--- a/python/lsst/daf/butler/queries/tree/__init__.py
+++ b/python/lsst/daf/butler/queries/tree/__init__.py
@@ -35,6 +35,5 @@
 from ._query_tree import *
 
 LogicalNot.model_rebuild()
-del LogicalNot
 
 Predicate.model_rebuild()