DOCSP-26183 replaces :doc: with improved admonitions (#2080)

Author: jmd-mongo

source/core/document.txt

@@ -302,7 +302,7 @@ Query filter documents specify the conditions that determine which
 records to select for read, update, and delete operations.
 
 You can use ``<field>:<value>`` expressions to specify the equality
-condition and :doc:`query operator </reference/operator/query>`
+condition and :ref:`query operator <query-projection-operators-top>`
 expressions.
 
 .. code-block:: javascript

source/includes/extracts-views.yaml

@@ -21,9 +21,8 @@ content: |
 ---
 ref: views-unsupported-projection-operators
 content: |
-   :method:`~db.collection.find()` operations on views do not support
-   the following :doc:`projection </reference/operator/projection>`
-   operators:
+   :method:`~db.collection.find()` operations on views do not support 
+   the following :ref:`query-projection-operators-top` operators:
 
    - :projection:`$`
    - :projection:`$elemMatch`

source/legacy-opcodes.txt

@@ -544,7 +544,7 @@ format of a OP_UPDATE message is the following:
    * - ``update``
 
      - BSON document that specifies the update to be performed. For
-       information on specifying updates see the :doc:`Update
-       Operations </tutorial/update-documents/>` documentation.
+       information on specifying updates see the :ref:`Update
+       Operations <update-operators>` documentation.
 
 There is no response to an OP_UPDATE message.

source/reference/bios-example-collection.txt

@@ -1,5 +1,7 @@
 :orphan:
 
+.. _bios-example-collection:
+
 ===============================
 The ``bios`` Example Collection
 ===============================

source/reference/command/mapReduce.txt

@@ -122,9 +122,9 @@ The command takes the following fields as arguments:
      - document
      - .. _cmd-mapreduce-query:
 
-       Optional. Specifies the selection criteria using :doc:`query operators
-       </reference/operator>` for determining the documents input to the
-       ``map`` function.
+       Optional. Specifies the selection criteria using :ref:`query operators
+       <query-projection-operators-top>` for determining the documents 
+       input to the ``map`` function.
 
    * - :ref:`sort <cmd-mapreduce-sort>`
      - document

source/reference/method/db.collection.deleteMany.txt

@@ -48,8 +48,8 @@ Definition
 
         - .. _deleteMany-filter:
 
-          Specifies deletion criteria using :doc:`query operators
-          </reference/operator>`. 
+          Specifies deletion criteria using :ref:`query operators
+          <query-selectors>`. 
 
           To delete all documents in a collection, pass in an empty document (``{ }``).
 
@@ -61,8 +61,8 @@ Definition
 
         - .. _deleteMany-wc:
 
-          Optional. A document expressing the :doc:`write concern
-          </reference/write-concern>`. Omit to use the default write concern.
+          Optional. A document expressing the :ref:`write concern
+          <write-concern>`. Omit to use the default write concern.
 
           .. include:: /includes/extracts/transactions-operations-write-concern.rst
 
@@ -84,8 +84,8 @@ Definition
 
         - .. _deleteMany-hint:
 
-          Optional. A document or string that specifies the :doc:`index
-          </indexes>` to use to support the :ref:`query predicate
+          Optional. A document or string that specifies the index 
+          to use to support the :ref:`query predicate
           <deleteMany-filter>`.
 
           The option can take an index specification document or the

source/reference/method/db.collection.find.txt

@@ -38,9 +38,10 @@ Definition
 
         - .. _method-find-query:
 
-          Optional. Specifies selection filter using :doc:`query operators
-          </reference/operator>`. To return all documents in a collection, omit
-          this parameter or pass an empty document (``{}``).
+          Optional. Specifies selection filter using :ref:`query 
+          operators <query-projection-operators-top>`. To return all 
+          documents in a collection, omit this parameter or pass an 
+          empty document (``{}``).
 
 
 
@@ -217,8 +218,8 @@ Client Disconnection
 Examples
 --------
 
-The examples in this section use documents from the :doc:`bios
-collection </reference/bios-example-collection>` where the documents
+The examples in this section use documents from the :ref:`bios
+collection <bios-example-collection>` where the documents
 generally have the form:
 
 .. code-block:: javascript
@@ -236,7 +237,7 @@ generally have the form:
    }
 
 To create and populate the ``bios`` collection, see
-:doc:`/reference/bios-example-collection`.
+:ref:`bios collection <bios-example-collection>`.
 
 Find All Documents in a Collection
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

source/reference/method/db.collection.findOne.txt

@@ -21,12 +21,12 @@ Definition
 
 
    Returns one document that satisfies the specified query criteria on
-   the collection or :doc:`view </core/views>`. If multiple documents
-   satisfy the query, this method returns the first document according
-   to the :term:`natural order` which reflects the order of documents
-   on the disk. In :term:`capped collections <capped collection>`,
-   natural order is the same as insertion order. If no document
-   satisfies the query, the method returns null.
+   the collection or :ref:`view <views-landing-page>`. If multiple 
+   documents satisfy the query, this method returns the first document 
+   according to the :term:`natural order` which reflects the order of 
+   documents on the disk. In :term:`capped collections 
+   <capped collection>`, natural order is the same as insertion order. 
+   If no document satisfies the query, the method returns null.
 
 
    .. list-table::
@@ -43,7 +43,8 @@ Definition
 
         - document
 
-        - Optional. Specifies query selection criteria using :doc:`query operators </reference/operator>`.
+        - Optional. Specifies query selection criteria using 
+          :ref:`query operators <query-projection-operators-top>`.
 
 
 
@@ -52,7 +53,7 @@ Definition
         - document
 
         - Optional. Specifies the fields to return using
-          :doc:`projection operators </reference/operator/projection>`.
+          :ref:`projection operators <query-projection-operators-top>`.
           Omit this parameter to return all fields in the matching
           document. For details, see :ref:`findOne-projection`.
 
@@ -143,7 +144,7 @@ With Empty Query Specification
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following operation returns a single document from
-the :doc:`bios collection </reference/bios-example-collection>`:
+the :ref:`bios collection <bios-example-collection>`:
 
 .. code-block:: javascript
 
@@ -153,9 +154,9 @@ With a Query Specification
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following operation returns the first matching document from the
-:doc:`bios collection </reference/bios-example-collection>` where either
-the field ``first`` in the embedded document ``name`` starts with the letter
-``G`` **or** where the field ``birth`` is less than ``new
+bios collection where either the field ``first`` in the embedded 
+document ``name`` starts with the letter ``G`` **or** where the field 
+``birth`` is less than ``new
 Date('01/01/1945')``:
 
 .. code-block:: javascript
@@ -179,9 +180,8 @@ unless the exclude is for the ``_id`` field.
 Specify the Fields to Return
 ````````````````````````````
 
-The following operation finds a document in the :doc:`bios collection
-</reference/bios-example-collection>` and returns only the ``name``,
-``contribs`` and ``_id`` fields:
+The following operation finds a document in the bios collection and 
+returns only the ``name``, ``contribs`` and ``_id`` fields:
 
 .. code-block:: javascript
 
@@ -193,11 +193,10 @@ The following operation finds a document in the :doc:`bios collection
 Return All but the Excluded Fields
 ``````````````````````````````````
 
-The following operation returns a document in the :doc:`bios collection
-</reference/bios-example-collection>` where the ``contribs`` field
-contains the element ``OOP`` and returns all fields *except* the ``_id``
-field, the ``first`` field in the ``name`` embedded document, and the
-``birth`` field:
+The following operation returns a document in the bios collection
+where the ``contribs`` field contains the element ``OOP`` and returns 
+all fields *except* the ``_id`` field, the ``first`` field in the 
+``name`` embedded document, and the ``birth`` field:
 
 .. code-block:: javascript
 

source/reference/method/db.collection.mapReduce.txt

@@ -140,8 +140,8 @@ The following table describes additional arguments that
 
      - document
 
-     - Specifies the selection criteria using :doc:`query operators
-       </reference/operator>` for determining the documents input to the
+     - Specifies the selection criteria using :ref:`query operators
+       <query-selectors>` for determining the documents input to the
        ``map`` function.
 
 

source/reference/method/db.collection.remove.txt

@@ -62,8 +62,8 @@ Definition
 
         - document
 
-        - Specifies deletion criteria using :doc:`query operators
-          </reference/operator>`. To delete all documents in a collection,
+        - Specifies deletion criteria using :ref:`query operators
+          <query-selectors>`. To delete all documents in a collection,
           pass an empty document (``{}``).
 
       * - ``justOne``

source/reference/method/db.collection.update.txt

@@ -143,9 +143,9 @@ parameters:
 
      - .. _update-wc:
 
-       Optional. A document expressing the :doc:`write concern
-       </reference/write-concern>`. Omit to use the default write
-       concern ``w: 1``.
+       Optional. A document expressing the :ref:`write concern
+       <write-concern>`. Omit to use the default write concern 
+       ``w: 1``.
 
        .. include:: /includes/extracts/transactions-operations-write-concern.rst
 
@@ -192,8 +192,8 @@ parameters:
 
      - .. _update-hint:
 
-       Optional. A document or string that specifies the :doc:`index
-       </indexes>` to use to support the :ref:`query predicate
+       Optional. A document or string that specifies the :ref:`index
+       <indexes>` to use to support the :ref:`query predicate
        <update-query>`.
 
        The option can take an index specification document or the index
@@ -313,9 +313,9 @@ To modify the **existing** shard key value with
 - You :red:`must` run on a :binary:`~bin.mongos`. Do :red:`not`
   issue the operation directly on the shard.
 
-- You :red:`must` run either in a :doc:`transaction
-  </core/transactions>` or as a :doc:`retryable write
-  </core/retryable-writes>`.
+- You :red:`must` run either in a :ref:`transaction
+  <transactions>` or as a :ref:`retryable write
+  <retryable-writes>`.
 
 - You :red:`must` specify ``multi: false``.
 
@@ -359,9 +359,9 @@ In addition, the following requirements also apply:
 
    * - To set to a non-``null`` value
 
-     - - :red:`Must` be performed either inside a :doc:`transaction
-         </core/transactions>` or as a :doc:`retryable write
-         </core/retryable-writes>`.
+     - - :red:`Must` be performed either inside a :ref:`transaction
+         <transactions>` or as a :ref:`retryable write
+         <retryable-writes>`.
 
        - :red:`Must` specify ``multi: false``.
 
@@ -519,7 +519,7 @@ The following tabs showcase a variety of common
       .. seealso::
 
          :update:`$set`, :update:`$inc`,
-         :doc:`/reference/operator/update`,
+         :ref:`update operators <update-operators>`
          :ref:`dot notation <document-dot-notation>`
 
    .. tab:: Arrays
@@ -616,7 +616,7 @@ The following tabs showcase a variety of common
 
       .. seealso::
 
-         :update:`$unset`, :update:`$rename`, :doc:`/reference/operator/update`
+         :update:`$unset`, :update:`$rename`, :ref:`update operators <update-operators>`
 
    .. tab:: Multiple
       :tabid: update-multiple
@@ -811,7 +811,7 @@ with :method:`~db.collection.update()`.
       from the equality clauses in the ``<query>`` parameter and
       applies the expressions from the ``<update>`` parameter.
 
-      :doc:`Comparison </reference/operator/query>` operations from
+      :ref:`Comparison <query-projection-operators-top>` operations from
       the ``<query>`` will not be included in the new document. If
       the new document does not include the ``_id`` field, MongoDB
       adds the ``_id`` field with an :ref:`objectid` value.
@@ -1049,10 +1049,9 @@ Update with Aggregation Pipeline
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Starting in MongoDB 4.2, the :method:`db.collection.update()` method
-can accept an :doc:`aggregation pipeline
-</core/aggregation-pipeline>` ``[ <stage1>, <stage2>, ... ]`` that
-specifies the modifications to perform. The pipeline can consist of
-the following stages:
+can accept an :ref:`aggregation pipeline <aggregation-pipeline>` 
+``[ <stage1>, <stage2>, ... ]`` that specifies the modifications to 
+perform. The pipeline can consist of the following stages:
 
 .. include:: /includes/list-update-agg-stages.rst
 
@@ -1124,7 +1123,7 @@ After the command, the collection contains the following documents:
 
 .. seealso::
 
-   :doc:`/tutorial/update-documents-with-aggregation-pipeline`
+   :ref:`updates-agg-pipeline`
 
 Perform Conditional Updates Based on Current Field Values
 `````````````````````````````````````````````````````````
@@ -1197,7 +1196,7 @@ After the command, the collection contains the following documents:
 
 .. seealso::
 
-   :doc:`/tutorial/update-documents-with-aggregation-pipeline`
+   :ref:`updates-agg-pipeline`
 
 .. _update-arrayFilters:
 
@@ -1402,8 +1401,8 @@ Use Variables in ``let``
 Override Default Write Concern
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The following operation to a replica set specifies a :doc:`write concern
-</reference/write-concern>` of ``w: 2`` with a ``wtimeout`` of 5000
+The following operation to a replica set specifies a :ref:`write concern
+<write-concern>` of ``w: 2`` with a ``wtimeout`` of 5000
 milliseconds. This operation either returns after the write propagates
 to both the primary and one secondary, or times out after 5 seconds.
 

source/reference/operator/aggregation-pipeline.txt

@@ -7,8 +7,8 @@ Aggregation Pipeline Stages
 .. default-domain:: mongodb
 
 In the :method:`db.collection.aggregate` method and
-:method:`db.aggregate` method, :doc:`pipeline
-</core/aggregation-pipeline>` stages appear in an array. Documents pass
+:method:`db.aggregate` method, :ref:`pipeline
+<aggregation-pipeline>` stages appear in an array. Documents pass
 through the stages in sequence.
 
 Stages
@@ -29,7 +29,7 @@ and :pipeline:`$changeStream` stages can appear multiple times in a pipeline.
 .. include:: /includes/extracts/agg-stages-db.collection.aggregate.rst
 
 For aggregation expression operators to use in the pipeline stages, see
-:doc:`/reference/operator/aggregation`.
+:ref:`aggregation-pipeline-operator-reference`.
 
 ``db.aggregate()`` Stages
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -216,8 +216,8 @@ Alphabetical Listing of Stages
 
    * - :pipeline:`$planCacheStats`
 
-     - Returns :doc:`plan cache </core/query-plans>` information for a
-       collection.
+     - Returns :ref:`plan cache <query-plans-query-optimization>` 
+       information for a collection.
 
 
    * - :pipeline:`$project`
@@ -260,7 +260,7 @@ Alphabetical Listing of Stages
      - Randomly selects the specified number of documents from its input.
 
 
-   * - :doc:`$search </reference/operator/aggregation/search>`
+   * - :pipeline:`$search`
 
      - Performs a full-text search of the field or fields in an Atlas 
        collection.
@@ -273,7 +273,7 @@ Alphabetical Listing of Stages
        To learn more, see :atlas:`Atlas Search Aggregation Pipeline 
        Stages </reference/atlas-search/query-syntax>`.
 
-   * - :doc:`$searchMeta </reference/operator/aggregation/searchMeta>`
+   * - :pipeline:`$searchMeta`
 
      - Returns different types of :ref:`metadata result 
        <fts-metadata-results>` documents for the :atlas:`Atlas Search