CDRIVER-4612 document management of search indexes

[kevinAlbs]

Summary

• Document management of Atlas Search Indexes.

Background & Motivation

DRIVERS-2637 adds new API to manage Atlas Search Indexes. This PR documents how to run the management commands with existing C driver API.

Rejected idea: Adding API

An API to model the specified Standard API for Search Indexes was considered but rejected.

The Search Indexes helpers do not have special option handling. IMO adding the API would not provide value to wrapping drivers. This PR proposes not adding the API, and instead documents how to manage Search Indexes. If the specified behavior of Search Indexes helpers changes in the future, adding helpers can be reconsidered.

Rejected idea: Adding end-to-end tests to Evergreen

End-to-end (E2E) tests in DRIVERS-2630 were decidedly not added. The proposed C driver changes do not add new API. The E2E tests in Evergreen may not add helpful test coverage. E2E tests require creating an Atlas cluster with setup-atlas-cluster.sh. A local run took 9m28s. I do not think it is worth the effort or maintenance burden.

example-manage-search-indexes was tested manually with an Atlas cluster created with setup-atlas-cluster.sh:

% ./cmake-build/src/libmongoc/example-manage-search-indexes $ATLAS_SEARCH_INDEXES_URI
Created index: "test-index"
Listing indexes:
  { "id" : "64c3c96874355a6d0050331f", "name" : "test-index", "status" : "PENDING", "queryable" : false, "latestDefinition" : { "mappings" : { "dynamic" : false } } }
Updated index: "test-index"
Dropped index: "test-index"

The JSON specification tests are added. The JSON specification tests may be a simpler and lower maintenance test of the documented approach for sending management commands: use of mongoc_collection_command_simple. The JSON specification tests can be removed if desired.

[eramongodb]

If this example is run against a non-Atlas server, this example fails on this command attempt and error with a "no such cmd" message. Can we consider adding an earlier "example must be run against Atlas" check and error to make the required conditions a bit more clear?

[kevinAlbs]

I like that idea. ee78062 adds an earlier check that $listSearchIndexes is supported, and prints an error suggesting the example may not be using Atlas if an error occurred.

[joshbsiegel]

LGTM