[CDRIVER-4651] Documentation on vcpkg installation + more (#1424)

* Docs additions and updates:

- Enable the documentation index. Begin using index entries.
- Add a reference page for Linux, Conand, and vcpkg packages and how
  they can be found/used.
- Add a tutorial section for installing via vcpkg.

* Add an in-source example/test that uses vcpkg

This is a very minimal example and test case that installs the
release (not local!) version of libbson and libmongoc, and then tests
that the application builds and runs correctly. There is no CI task
for this yet, as it is unstable and does not make use of the local
source tree. Future updates may make a more thorough test case that
overrides the source for the vcpkg mongo-c-driver port to use the local
source tree, thus giving a route for automated testing of changes
against the third-party portfile.

* Add links to external port+recipes
* Tweak inclusion of the genindex page.

Including the genindex in a toctree seems to create a conflict with
the full_index page which tries to include the root `index.rst` via
another toctree? This is odd, but easy enough to work around.

Author: vector-of-bool

Earthfile

@@ -245,6 +245,45 @@ multibuild:
             --sasl=Cyrus --sasl=off \
             --tls=LibreSSL
 
+# test-vcpkg-classic :
+#   Builds src/libmongoc/examples/cmake/vcpkg by using vcpkg to download and
+#   install a mongo-c-driver build in "classic mode". *Does not* use the local
+#   mongo-c-driver repository.
+test-vcpkg-classic:
+    FROM +vcpkg-base
+    RUN vcpkg install mongo-c-driver
+    RUN rm -rf _build && \
+        make test-classic
+
+# test-vcpkg-manifest-mode :
+#   Builds src/libmongoc/examples/cmake/vcpkg by using vcpkg to download and
+#   install a mongo-c-driver package based on the content of a vcpkg.json manifest
+#   that is injected into the project.
+test-vcpkg-manifest-mode:
+    FROM +vcpkg-base
+    RUN apk add jq
+    RUN jq -n ' { \
+            name: "test-app", \
+            version: "1.2.3", \
+            dependencies: ["mongo-c-driver"], \
+        }' > vcpkg.json && \
+        cat vcpkg.json
+    RUN rm -rf _build && \
+        make test-manifest-mode
+
+vcpkg-base:
+    FROM alpine:3.18
+    RUN apk add cmake curl gcc g++ musl-dev ninja-is-really-ninja zip unzip tar \
+                build-base git pkgconf perl bash linux-headers
+    ENV VCPKG_ROOT=/opt/vcpkg-git
+    ENV VCPKG_FORCE_SYSTEM_BINARIES=1
+    GIT CLONE --branch=2023.06.20 https://github.com/microsoft/vcpkg $VCPKG_ROOT
+    RUN sh $VCPKG_ROOT/bootstrap-vcpkg.sh -disableMetrics && \
+        install -spD -m 755 $VCPKG_ROOT/vcpkg /usr/local/bin/
+    LET src_dir=/opt/mongoc-vcpkg-example
+    COPY src/libmongoc/examples/cmake/vcpkg/ $src_dir
+    WORKDIR $src_dir
+
 # run :
 #   Run one or more targets simultaneously.
 #

src/libmongoc/doc/conf.py

@@ -105,7 +105,7 @@ def _maybe_update_inventories(app: Sphinx, config: Config):
 html_theme = "furo"
 html_title = html_shorttitle = "libmongoc %s" % version
 # html_favicon = None
-html_use_index = False
+html_use_index = True
 
 rst_prolog = rf"""
 .. |qenc:is-experimental| replace::

src/libmongoc/doc/index.rst

@@ -26,3 +26,6 @@ It depends on :doc:`libbson <bson:index>` to generate and parse BSON documents,
    guides
    api
    application-performance-monitoring
+
+
+* :ref:`genindex`

src/libmongoc/doc/learn/get/from-source.rst

@@ -354,7 +354,7 @@ with |libmongoc|. Follow the process at :ref:`learn.get.build` and
 
 .. [#vs_env]
 
-  If you with to configure and build the project using Microsoft Visual C++,
+  If you wish to configure and build the project using Microsoft Visual C++,
   then the Visual C++ tools and environment variables may need to be set when
   running any CMake or build command.
 

src/libmongoc/doc/learn/get/installing.rst

@@ -11,14 +11,16 @@ Installing Prebuilt MongoDB C Driver Libraries
 .. _Homebrew: https://brew.sh/
 
 The |libmongoc| and |libbson| libraries are often available in the package
-management repositories of `common Linux distributions <linux_>`_ and
-`macOS via Homebrew <macos_>`_.
+management repositories of `common Linux distributions <installing.linux_>`_ and
+`macOS via Homebrew <installing.macos_>`_.
 
 .. note::
 
-  For Windows, it is recommended to instead
+  For :index:`Windows`, it is recommended to instead
   :doc:`build the libraries from source <from-source>`, for maximum
-  compatibility with the local toolchain.
+  compatibility with the local toolchain. Building from source can be automated
+  by using a from-source library package management tool such as Conan_ or
+  vcpkg_ (See: :ref:`installing.pkgman`).
 
 .. caution::
 
@@ -30,8 +32,110 @@ management repositories of `common Linux distributions <linux_>`_ and
   For the most up-to-date versions of the C driver libraries, prefer to instead
   :doc:`build from source <from-source>`.
 
+.. seealso::
 
-.. _linux:
+  For a listing and common reference on available packages, refer to
+  :doc:`/ref/packages`.
+
+
+.. index::
+  package managers; Conan
+  package managers; vcpkg
+  pair: installation; package managers
+  :name: installing.pkgman
+
+Cross Platform Installs Using Library Package Managers
+******************************************************
+
+Various library package managers offer |libbson| and |libmongoc| as installable
+packages, including Conan_ and vcpkg_. This section will detail how to install
+using those tools.
+
+.. _conan: https://conan.io/
+.. _vcpkg: https://vcpkg.io/
+
+
+.. index::
+  ! pair: installation; vcpkg
+
+Installing using vcpkg
+======================
+
+.. note::
+  This page will not detail how to get started using vcpkg_. For that, refer to
+  `Get started with vcpkg`__
+
+  __ https://vcpkg.io/en/getting-started
+
+.. tab-set::
+
+  .. tab-item:: vcpkg Manifest Mode (Recommended)
+
+    In `vcpkg manifest mode`__, add the desired libraries to your project's
+    ``vcpkg.json`` manifest file:
+
+    __ https://learn.microsoft.com/en-us/vcpkg/users/manifests
+
+    .. code-block:: js
+      :caption: ``vcpkg.json``
+      :linenos:
+
+      {
+        // ...
+        "dependencies": [
+          // ...
+          "mongo-c-driver"
+        ]
+      }
+
+    When you build a CMake project with vcpkg integration and have a
+    ``vcpkg.json`` manifest file, vcpkg will automatically install the project's
+    dependencies before proceeding with the configuration phase, so no
+    additional manual work is required.
+
+
+  .. tab-item:: vcpkg Classic Mode
+
+    In `vcpkg classic mode`__, |libbson| and |libmongoc| can be installed through the
+    names ``libbson`` and ``mongo-c-driver``, respectively::
+
+      $ vcpkg install mongo-c-driver
+
+    __ https://learn.microsoft.com/en-us/vcpkg/users/classic-mode
+
+    (Installing ``mongo-c-driver`` will transitively install |libbson| as well.)
+
+    When the |libmongoc| and |libbson| packages are installed and vcpkg has been
+    properly integrated into your build system, the desired libraries will be
+    available for import.
+
+With CMake, the standard config-file package will be available, as well as the
+generated ``IMPORTED`` targets:
+
+.. code-block:: cmake
+  :caption: ``CMakeLists.txt``
+
+  find_package(mongoc-1.0 CONFIG REQUIRED)
+  target_link_libraries(my-application
+      PRIVATE $<IF:$<TARGET_EXISTS:mongo::mongoc_shared>,mongo::mongoc_shared,mongo::mongoc_static>)
+
+.. note::
+
+  The large ``$<IF:$<TARGET_EXISTS...>:...>`` generator expression
+  (:external:doc:`manual/cmake-generator-expressions.7`) can be used to switch
+  the link type of |libmongoc| based on whichever form is available from the
+  ``find_package()`` command. |libmongoc| supports building with both *dynamic*
+  and *static* library types, but vcpkg will only install one of the two library
+  types at a time.
+
+Configuring a CMake project with vcpkg integration is a matter of setting the
+CMake toolchain file at the initial configure command::
+
+  $ cmake -S . -B _build -D CMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
+
+.. index::
+  ! pair: Linux; installation
+  :name: installing.linux
 
 Installing in Linux
 *******************
@@ -48,7 +152,20 @@ The following Linux distributions provide |libbson| and |libmongoc| packages:
 - `Debian <debian_>`_ and Debian-based distributions, including
   `Ubuntu <debian_>`_ and Ubuntu derivatives, via APT.
 
+.. seealso::
+
+  For a list of available packages and package options, see:
+  :doc:`/ref/packages`.
 
+
+.. index::
+  !pair: installation; RHEL
+  !pair: installation; Fedora
+  !pair: installation; CentOS
+  !pair: installation; Rocky Linux
+  !pair: installation; AlmaLinux
+  !pair: installation; Yum
+  !pair: installation; DNF
 .. _redhat:
 
 RedHat-based Systems
@@ -91,6 +208,10 @@ To install the full C database driver (|libmongoc|), install
   # yum install mongo-c-driver-devel
 
 
+.. index::
+    !pair: installation; Debian
+    !pair: installation; Ubuntu
+    !pair: installation; APT
 .. _debian:
 
 Debian-based Systems
@@ -112,26 +233,25 @@ To install |libmongoc| (which will also install |libbson|)::
   # apt install libmongoc-dev
 
 
-.. _macos:
+.. index::
+  !pair: installation; macOS
+  !pair: installation; Homebrew
+  package managers; Homebrew
+.. _installing.macos:
 
 Installing on macOS with Homebrew
 *********************************
 
 If you are using a macOS system, the C driver libraries (including both
-|libmongoc| and |libbson|) may be installed using the Homebrew_ package manager [#macos_brew]_
-with the following command::
+|libmongoc| and |libbson|) may be installed using the Homebrew_ package manager
+[#macos_brew]_ with the following command::
 
   $ brew install mongo-c-driver
 
 .. note::
 
   Homebrew does not provide separate packages for |libbson| and |libmongoc|.
 
-
-.. todo
-  Packages for Windows, via Conan, and via vcpkg
-
-
 .. [#macos_brew]
 
   The Homebrew_ package manager is not installed by default on macOS. For

src/libmongoc/doc/mongoc_client_encryption_opts_set_kms_credential_provider_callback.rst

@@ -34,6 +34,12 @@ Parameters
 .. rubric:: Related:
 
 .. c:type:: mongoc_kms_credentials_provider_callback_fn
+  :noindexentry:
+
+  .. -
+    The :noindexentry: prevents a one-off index entry for this item.
+    Most entities are not documented as Sphinx objects, and thus do not generate
+    index entries. Future changes may flip the script.
 
   .. code-block:: c