PYCBC-1693: Add CollectionQueryIndexManager to API reference

Motivation
==========
CollectionQueryIndexManager is the preferred API to manage query indexes in clusters with collection support (which is now all supported server versions). We should include that API in the reference.

Changes
=======
* Add CollectionQueryIndexManager to the API reference.
* Update options docs to link to CollectionQueryIndexManager in collection_name/scope_name deprecation notices.

Change-Id: Ib74459b6b25d9e7ac4c504c7d4510d28d5f640a9
Reviewed-on: https://review.couchbase.org/c/couchbase-python-client/+/230505
Reviewed-by: Jared Casey <jared.casey@couchbase.com>
Tested-by: Build Bot <build@couchbase.com>

Author: DemetrisChr

couchbase/management/options.py

@@ -531,9 +531,9 @@ class GetAllQueryIndexOptions(dict):
         All management options should be imported from `couchbase.management.options`.
 
     Args:
-        collection_name (str, optional):  ** DEPRECATED ** - use `~couchbase.management.queries.CollectionQueryIndexManager`.
+        collection_name (str, optional):  **DEPRECATED** - use :class:`~couchbase.management.queries.CollectionQueryIndexManager`.
             Specifies the collection of the indexes.
-        scope_name (str, optional):  ** DEPRECATED ** - use `~couchbase.management.queries.CollectionQueryIndexManager`.
+        scope_name (str, optional):  **DEPRECATED** - use :class:`~couchbase.management.queries.CollectionQueryIndexManager`.
             Specifies the scope of the indexes.
         timeout (timedelta, optional): The timeout for this operation. Defaults to global
             management operation timeout.
@@ -559,15 +559,15 @@ class CreateQueryIndexOptions(dict):
         All management options should be imported from `couchbase.management.options`.
 
     Args:
-        collection_name (str, optional):  ** DEPRECATED ** - use `~couchbase.management.queries.CollectionQueryIndexManager`.
+        collection_name (str, optional):  **DEPRECATED** - use :class:`~couchbase.management.queries.CollectionQueryIndexManager`.
             Specifies the collection of the index.
         condition (str, optional): Specifies the 'where' condition for partial index creation.
         deferred (bool, optional): Specifies whether this index creation should be deferred until
             a later point in time when they can be explicitly built together.
         ignore_if_exists (bool, optional): Whether or not the call should ignore the
             index already existing when determining whether the call was successful.
         num_replicas (int, optional): The number of replicas of this index that should be created.
-        scope_name (str, optional):  ** DEPRECATED ** - use `~couchbase.management.queries.CollectionQueryIndexManager`.
+        scope_name (str, optional):  **DEPRECATED** - use :class:`~couchbase.management.queries.CollectionQueryIndexManager`.
             Specifies the scope of the index.
         timeout (timedelta, optional): The timeout for this operation. Defaults to global
             management operation timeout.
@@ -599,7 +599,7 @@ class CreatePrimaryQueryIndexOptions(dict):
         All management options should be imported from `couchbase.management.options`.
 
     Args:
-        collection_name (str, optional):  ** DEPRECATED ** - use `~couchbase.management.queries.CollectionQueryIndexManager`.
+        collection_name (str, optional):  **DEPRECATED** - use :class:`~couchbase.management.queries.CollectionQueryIndexManager`.
             Specifies the collection of the index.
         condition (str, optional): Specifies the 'where' condition for partial index creation.
         deferred (bool, optional): Specifies whether this index creation should be deferred until
@@ -608,7 +608,7 @@ class CreatePrimaryQueryIndexOptions(dict):
             index already existing when determining whether the call was successful.
         index_name (str, optional): Specifies the name of the primary index.
         num_replicas (int, optional): The number of replicas of this index that should be created.
-        scope_name (str, optional):  ** DEPRECATED ** - use `~couchbase.management.queries.CollectionQueryIndexManager`.
+        scope_name (str, optional):  **DEPRECATED** - use :class:`~couchbase.management.queries.CollectionQueryIndexManager`.
             Specifies the scope of the index.
         timeout (timedelta, optional): The timeout for this operation. Defaults to global
             management operation timeout.
@@ -641,11 +641,11 @@ class DropQueryIndexOptions(dict):
         All management options should be imported from `couchbase.management.options`.
 
     Args:
-        collection_name (str, optional):  ** DEPRECATED ** - use `~couchbase.management.queries.CollectionQueryIndexManager`.
+        collection_name (str, optional):  **DEPRECATED** - use :class:`~couchbase.management.queries.CollectionQueryIndexManager`.
             Specifies the collection of the index.
         ignore_if_not_exists (bool, optional): Whether or not the call should ignore the
             index not existing when determining whether the call was successful.
-        scope_name (str, optional):  ** DEPRECATED ** - use `~couchbase.management.queries.CollectionQueryIndexManager`.
+        scope_name (str, optional):  **DEPRECATED** - use :class:`~couchbase.management.queries.CollectionQueryIndexManager`.
             Specifies the scope of the index.
         timeout (timedelta, optional): The timeout for this operation. Defaults to global
             management operation timeout.
@@ -672,12 +672,12 @@ class DropPrimaryQueryIndexOptions(dict):
         All management options should be imported from `couchbase.management.options`.
 
     Args:
-        collection_name (str, optional): ** DEPRECATED ** - use `~couchbase.management.queries.CollectionQueryIndexManager`.
+        collection_name (str, optional): **DEPRECATED** - use :class:`~couchbase.management.queries.CollectionQueryIndexManager`.
             Specifies the collection of the index.
         ignore_if_not_exists (bool, optional): Whether or not the call should ignore the
             index not existing when determining whether the call was successful.
         index_name (str, optional): Specifies the name of the primary index.
-        scope_name (str, optional):  ** DEPRECATED ** - use `~couchbase.management.queries.CollectionQueryIndexManager`.
+        scope_name (str, optional):  **DEPRECATED** - use :class:`~couchbase.management.queries.CollectionQueryIndexManager`.
             Specifies the scope of the index.
         timeout (timedelta, optional): The timeout for this operation. Defaults to global
             management operation timeout.
@@ -705,9 +705,9 @@ class WatchQueryIndexOptions(dict):
         All management options should be imported from `couchbase.management.options`.
 
     Args:
-        collection_name (str, optional):  ** DEPRECATED ** - use `~couchbase.management.queries.CollectionQueryIndexManager`.
+        collection_name (str, optional):  **DEPRECATED** - use :class:`~couchbase.management.queries.CollectionQueryIndexManager`.
             Specifies the collection of the index.
-        scope_name (str, optional):  ** DEPRECATED ** - use `~couchbase.management.queries.CollectionQueryIndexManager`.
+        scope_name (str, optional):  **DEPRECATED** - use :class:`~couchbase.management.queries.CollectionQueryIndexManager`.
             Specifies the scope of the index.
         timeout (timedelta, optional): The timeout for this operation. Defaults to global
             management operation timeout.
@@ -736,9 +736,9 @@ class BuildDeferredQueryIndexOptions(dict):
         All management options should be imported from `couchbase.management.options`.
 
     Args:
-        collection_name (str, optional):  ** DEPRECATED ** - use `~couchbase.management.queries.CollectionQueryIndexManager`.
+        collection_name (str, optional):  **DEPRECATED** - use :class:`~couchbase.management.queries.CollectionQueryIndexManager`.
             Specifies the collection of the index.
-        scope_name (str, optional):  ** DEPRECATED ** - use `~couchbase.management.queries.CollectionQueryIndexManager`.
+        scope_name (str, optional):  **DEPRECATED** - use :class:`~couchbase.management.queries.CollectionQueryIndexManager`.
             Specifies the scope of the index.
         timeout (timedelta, optional): The timeout for this operation. Defaults to global
             management operation timeout.

couchbase/management/queries.py

@@ -38,14 +38,20 @@
 
 
 class QueryIndexManager(QueryIndexManagerLogic):
+    """
+    Performs management operations on query indexes.
+
+    For managing query indexes at the collection level, :class:`.CollectionQueryIndexManager` should be used.
+    """
+
     def __init__(self, connection):
         super().__init__(connection)
 
     @BlockingMgmtWrapper.block(None, ManagementType.QueryIndexMgmt, QueryIndexManagerLogic._ERROR_MAPPING)
     def create_index(self,
                      bucket_name,   # type: str
                      index_name,    # type: str
-                     keys,        # type: Iterable[str]
+                     keys,          # type: Iterable[str]
                      *options,      # type: CreateQueryIndexOptions
                      **kwargs       # type: Dict[str, Any]
                      ) -> None:
@@ -288,6 +294,10 @@ def check_indexes(index_names, indexes):
 
 
 class CollectionQueryIndexManager(QueryIndexManagerLogic):
+    """
+    Performs management operations on query indexes at the collection level.
+    """
+
     def __init__(self, connection, bucket_name, scope_name, collection_name):
         self._bucket_name = bucket_name
         self._scope_name = scope_name

docs/couchbase_api/couchbase_management.rst

@@ -100,6 +100,16 @@ Query Index Management
 
 .. module:: couchbase.management.queries
 
+.. autoclass:: CollectionQueryIndexManager
+
+    .. automethod:: build_deferred_indexes
+    .. automethod:: create_index
+    .. automethod:: create_primary_index
+    .. automethod:: drop_index
+    .. automethod:: drop_primary_index
+    .. automethod:: get_all_indexes
+    .. automethod:: watch_indexes
+
 .. autoclass:: QueryIndexManager
 
     .. automethod:: build_deferred_indexes