minor tweaks to examples

.gitignore

@@ -51,6 +51,7 @@ primer/source/.static
 primer/source/*.rst
 primer/source/core/*.rst
 primer/source/includes/example*.txt
+primer/source/includes/example-*.rst
 primer/source/includes/driver-table.rst
 primer/source/includes/fact-installation-bind-ip-default-in-config.rst
 primer/source/includes/fact-installation-directories.rst

primer/config/primer-migrations-java-examples.yaml

@@ -15,7 +15,7 @@ truncate:
    end-before: 38
 ---
 source: build/java-examples/driver/src/examples/primer/AggregatePrimer.java
-target: includes/example-java-group-documents-by-a-field-and-calculate-count-pre1.txt
+target: includes/example-java-group-documents-by-a-field-and-calculate-count-pre1.rst
 transform: 
   regex: "^        // @pre: "
   replace: ""
@@ -33,7 +33,7 @@ truncate:
    end-before: 48
 ---
 source: build/java-examples/driver/src/examples/primer/AggregatePrimer.java
-target: includes/example-java-group-documents-by-a-field-and-calculate-count-results.txt
+target: includes/example-java-group-documents-by-a-field-and-calculate-count-results.rst
 transform: 
   - regex: "^        "
     replace: ""
@@ -51,7 +51,7 @@ truncate:
    end-before: 72
 ---
 source: build/java-examples/driver/src/examples/primer/AggregatePrimer.java
-target: includes/example-java-filter-and-group-documents-pre1.txt
+target: includes/example-java-filter-and-group-documents-pre1.rst
 transform: 
   regex: "^        // @pre: "
   replace: ""
@@ -69,7 +69,7 @@ truncate:
    end-before: 82
 ---
 source: build/java-examples/driver/src/examples/primer/AggregatePrimer.java
-target: includes/example-java-filter-and-group-documents-results.txt
+target: includes/example-java-filter-and-group-documents-results.rst
 transform: 
   - regex: "^        "
     replace: ""
@@ -93,7 +93,7 @@ truncate:
    end-before: 60
 ---
 source: build/java-examples/driver/src/examples/primer/InsertPrimer.java
-target: includes/example-java-insert-a-document-post.txt
+target: includes/example-java-insert-a-document-post.rst
 transform: 
   regex: "^        // @post: "
   replace: ""
@@ -117,7 +117,7 @@ truncate:
    end-before: 39
 ---
 source: build/java-examples/driver/src/examples/primer/QueryPrimer.java
-target: includes/example-java-query-all-pre1.txt
+target: includes/example-java-query-all-pre1.rst
 transform: 
   regex: "^        // @pre: "
   replace: ""
@@ -144,7 +144,7 @@ truncate:
    end-before: 61
 ---
 source: build/java-examples/driver/src/examples/primer/QueryPrimer.java
-target: includes/example-java-logical-and-pre1.txt
+target: includes/example-java-logical-and-pre1.rst
 transform: 
   regex: "^        // @pre: "
   replace: ""
@@ -162,7 +162,7 @@ truncate:
    end-before: 71
 ---
 source: build/java-examples/driver/src/examples/primer/QueryPrimer.java
-target: includes/example-java-logical-and-pre2.txt
+target: includes/example-java-logical-and-pre2.rst
 transform: 
   regex: "^        // @pre: "
   replace: ""
@@ -189,7 +189,7 @@ truncate:
    end-before: 89
 ---
 source: build/java-examples/driver/src/examples/primer/QueryPrimer.java
-target: includes/example-java-logical-or-pre1.txt
+target: includes/example-java-logical-or-pre1.rst
 transform: 
   regex: "^        // @pre: "
   replace: ""
@@ -207,7 +207,7 @@ truncate:
    end-before: 99
 ---
 source: build/java-examples/driver/src/examples/primer/QueryPrimer.java
-target: includes/example-java-logical-or-pre2.txt
+target: includes/example-java-logical-or-pre2.rst
 transform: 
   regex: "^        // @pre: "
   replace: ""
@@ -234,7 +234,7 @@ truncate:
    end-before: 115
 ---
 source: build/java-examples/driver/src/examples/primer/QueryPrimer.java
-target: includes/example-java-query-top-level-field-pre1.txt
+target: includes/example-java-query-top-level-field-pre1.rst
 transform: 
   regex: "^        // @pre: "
   replace: ""
@@ -252,7 +252,7 @@ truncate:
    end-before: 125
 ---
 source: build/java-examples/driver/src/examples/primer/QueryPrimer.java
-target: includes/example-java-query-top-level-field-pre2.txt
+target: includes/example-java-query-top-level-field-pre2.rst
 transform: 
   regex: "^        // @pre: "
   replace: ""
@@ -279,7 +279,7 @@ truncate:
    end-before: 140
 ---
 source: build/java-examples/driver/src/examples/primer/QueryPrimer.java
-target: includes/example-java-query-embedded-document-pre1.txt
+target: includes/example-java-query-embedded-document-pre1.rst
 transform: 
   regex: "^        // @pre: "
   replace: ""
@@ -297,7 +297,7 @@ truncate:
    end-before: 150
 ---
 source: build/java-examples/driver/src/examples/primer/QueryPrimer.java
-target: includes/example-java-query-embedded-document-pre2.txt
+target: includes/example-java-query-embedded-document-pre2.rst
 transform: 
   regex: "^        // @pre: "
   replace: ""
@@ -324,7 +324,7 @@ truncate:
    end-before: 165
 ---
 source: build/java-examples/driver/src/examples/primer/QueryPrimer.java
-target: includes/example-java-query-field-in-array-pre1.txt
+target: includes/example-java-query-field-in-array-pre1.rst
 transform: 
   regex: "^        // @pre: "
   replace: ""
@@ -342,7 +342,7 @@ truncate:
    end-before: 175
 ---
 source: build/java-examples/driver/src/examples/primer/QueryPrimer.java
-target: includes/example-java-query-field-in-array-pre2.txt
+target: includes/example-java-query-field-in-array-pre2.rst
 transform: 
   regex: "^        // @pre: "
   replace: ""
@@ -369,7 +369,7 @@ truncate:
    end-before: 190
 ---
 source: build/java-examples/driver/src/examples/primer/QueryPrimer.java
-target: includes/example-java-greater-than-pre1.txt
+target: includes/example-java-greater-than-pre1.rst
 transform: 
   regex: "^        // @pre: "
   replace: ""
@@ -387,7 +387,7 @@ truncate:
    end-before: 200
 ---
 source: build/java-examples/driver/src/examples/primer/QueryPrimer.java
-target: includes/example-java-greater-than-pre2.txt
+target: includes/example-java-greater-than-pre2.rst
 transform: 
   regex: "^        // @pre: "
   replace: ""
@@ -414,7 +414,7 @@ truncate:
    end-before: 215
 ---
 source: build/java-examples/driver/src/examples/primer/QueryPrimer.java
-target: includes/example-java-less-than-pre1.txt
+target: includes/example-java-less-than-pre1.rst
 transform: 
   regex: "^        // @pre: "
   replace: ""
@@ -432,7 +432,7 @@ truncate:
    end-before: 225
 ---
 source: build/java-examples/driver/src/examples/primer/QueryPrimer.java
-target: includes/example-java-less-than-pre2.txt
+target: includes/example-java-less-than-pre2.rst
 transform: 
   regex: "^        // @pre: "
   replace: ""
@@ -459,7 +459,7 @@ truncate:
    end-before: 241
 ---
 source: build/java-examples/driver/src/examples/primer/QueryPrimer.java
-target: includes/example-java-sort-pre1.txt
+target: includes/example-java-sort-pre1.rst
 transform: 
   regex: "^        // @pre: "
   replace: ""
@@ -477,7 +477,7 @@ truncate:
    end-before: 251
 ---
 source: build/java-examples/driver/src/examples/primer/QueryPrimer.java
-target: includes/example-java-sort-pre2.txt
+target: includes/example-java-sort-pre2.rst
 transform: 
   regex: "^        // @pre: "
   replace: ""
@@ -510,7 +510,7 @@ truncate:
    end-before: 41
 ---
 source: build/java-examples/driver/src/examples/primer/UpdatePrimer.java
-target: includes/example-java-update-top-level-fields-post.txt
+target: includes/example-java-update-top-level-fields-post.rst
 transform: 
   - regex: "^        "
     replace: ""
@@ -530,7 +530,7 @@ truncate:
    end-before: 59
 ---
 source: build/java-examples/driver/src/examples/primer/UpdatePrimer.java
-target: includes/example-java-update-embedded-field-post.txt
+target: includes/example-java-update-embedded-field-post.rst
 transform: 
   - regex: "^        "
     replace: ""
@@ -550,7 +550,7 @@ truncate:
    end-before: 79
 ---
 source: build/java-examples/driver/src/examples/primer/UpdatePrimer.java
-target: includes/example-java-update-multiple-documents-post.txt
+target: includes/example-java-update-multiple-documents-post.rst
 transform: 
   - regex: "^        "
     replace: ""
@@ -570,7 +570,7 @@ truncate:
    end-before: 104
 ---
 source: build/java-examples/driver/src/examples/primer/UpdatePrimer.java
-target: includes/example-java-replace-document-post.txt
+target: includes/example-java-replace-document-post.rst
 transform: 
   - regex: "^       "
     replace: ""
@@ -596,7 +596,7 @@ truncate:
    end-before: 34
 ---
 source: build/java-examples/driver/src/examples/primer/IndexesPrimer.java
-target: includes/example-java-single-field-index-post.txt
+target: includes/example-java-single-field-index-post.rst
 transform: 
   regex: "^        // @post: "
   replace: ""
@@ -614,7 +614,7 @@ truncate:
    end-before: 45
 ---
 source: build/java-examples/driver/src/examples/primer/IndexesPrimer.java
-target: includes/example-java-create-compound-index-post.txt
+target: includes/example-java-create-compound-index-post.rst
 transform: 
   regex: "^        // @post: "
   replace: ""
@@ -638,7 +638,7 @@ truncate:
    end-before: 32
 ---
 source: build/java-examples/driver/src/examples/primer/RemovePrimer.java
-target: includes/example-java-remove-matching-documents-post.txt
+target: includes/example-java-remove-matching-documents-post.rst
 transform: 
   - regex: "^        "
     replace: ""
@@ -658,7 +658,7 @@ truncate:
    end-before: 48
 ---
 source: build/java-examples/driver/src/examples/primer/RemovePrimer.java
-target: includes/example-java-remove-all-documents-post.txt
+target: includes/example-java-remove-all-documents-post.rst
 transform: 
   - regex: "^        "
     replace: ""

primer/source/includes/examples-aggregation-base.yaml

@@ -44,4 +44,8 @@ pre: |
   dollar sign ``$``.
 post: |
   The result set consists of the following documents:
+final: |
+  The ``_id`` field contains the distinct ``zipcode`` value, i.e., the
+  group by key value.
+
 ...

primer/source/includes/examples-aggregation.yaml

@@ -215,7 +215,7 @@ operation:
 
   - pre: "The result set consists of the following documents:"
 
-  - literalinclude: includes/example-java-group-documents-by-a-field-and-calculate-count-results.txt
+  - literalinclude: includes/example-java-group-documents-by-a-field-and-calculate-count-results.rst
 post: ''
 ---
 source:
@@ -235,6 +235,6 @@ operation:
 
   - pre: "The result set consists of the following documents:"
 
-  - literalinclude: includes/example-java-filter-and-group-documents-results.txt
+  - literalinclude: includes/example-java-filter-and-group-documents-results.rst
 post: ''
 ...

primer/source/includes/examples-index.yaml

@@ -191,7 +191,7 @@ edition: java
 operation:
   - literalinclude: includes/example-java-single-field-index.java
     language: java
-  - post:  ".. include:: includes/example-java-single-field-index-post.txt"
+  - post:  ".. include:: includes/example-java-single-field-index-post.rst"
 ---
 source:
   file: examples-index-base.yaml
@@ -202,5 +202,5 @@ operation:
   - literalinclude: includes/example-java-create-compound-index.java
     language: java
 
-  - post: ".. include:: includes/example-java-create-compound-index-post.txt"
+  - post: ".. include:: includes/example-java-create-compound-index-post.rst"
 ...

primer/source/includes/examples-insert.yaml

@@ -59,8 +59,8 @@ source:
 ref: py-insert-a-document
 edition: python
 operation:
-  language: python
-  code: |
+  - language: python
+    code: |
       from datetime import datetime
       result = db.restaurants.insert_one(
           {
@@ -88,11 +88,19 @@ operation:
               "restaurant_id": "41704620"
           }
       )
-post: |
-  The operation returns an :py:class:`~pymongo.results.InsertOneResult` object,
-  which includes the ``_id`` of the inserted document.
+  - pre: |
+      The operation returns an
+      :py:class:`~pymongo.results.InsertOneResult` object, which
+      includes an attribute ``inserted_id`` that contains the ``_id``
+      of the inserted document. Access the ``inserted_id`` attribute:
+    language: python
+    code: |
+
+      result.inserted_id
+    post: |
+      The :manual:`ObjectId </reference/object-id>` of your inserted
+      document will differ from the one shown.
 results: |
-  result.inserted_id
   ObjectId("54c1478ec2341ddf130f62b7")
 replacement:
   insertMethod: :py:meth:`~pymongo.collection.Collection.insert_one`
@@ -181,7 +189,7 @@ operation:
   - literalinclude: includes/example-java-insert-a-document.java
     language: java
   - post: |
-      .. include:: includes/example-java-insert-a-document-post.txt
+      .. include:: includes/example-java-insert-a-document-post.rst
 replacement:
   clientName: the driver
   insertMethod: "insertOne_"

primer/source/includes/examples-query-all.yaml

@@ -99,7 +99,7 @@ operation:
   - literalinclude: includes/example-java-query-all.java
     language: java
   - pre: |
-      .. include:: includes/example-java-query-all-pre1.txt
+      .. include:: includes/example-java-query-all-pre1.rst
   - literalinclude: includes/example-java-query-all-pre1.java
     language: java
 

primer/source/includes/examples-query-combination.yaml

@@ -179,7 +179,7 @@ operation:
        The result set includes only the documents that matched all specified
        criteria.
   - pre: |
-      .. include:: includes/example-java-logical-and-pre1.txt
+      .. include:: includes/example-java-logical-and-pre1.rst
   - literalinclude: includes/example-java-logical-and-pre1.java
     language: java
   - pre: |
@@ -200,7 +200,7 @@ operation:
        The result set includes only the documents that match either
        conditions.
   - pre: |
-      .. include:: includes/example-java-logical-or-pre1.txt
+      .. include:: includes/example-java-logical-or-pre1.rst
   - literalinclude: includes/example-java-logical-or-pre1.java
     language: java
   - pre: |