External qa (#56)

* autobuilder

* testing term role

* term doens't work

* index improvements

* update bson page

* linked to README for testing (#45)

* update api links to 1.7.2 (#46)

* update api links to 1.7.2

* Update source/fundamentals/bson.txt

Co-authored-by: kyuan-mongodb <[email protected]>

Co-authored-by: kyuan-mongodb <[email protected]>

* context page suggestions (#47)

* DOCSP-18732 quick start page (#48)

* incorporated quickstart feedback

* Docsp 18731 (#50)

* fix broken links

* comment out todo

* change link to get uri

* update to use godotenv and bson.M

* add godotenv to main.go quickstart

* nits

* text updates for examples

* missed click here

* DOCSP-18739 (#51)

* implemented linking suggestion

* DOCSP-18734 connection guide (#52)

* updated section headers

* Docsp 18736 (#53)

* hide link to blank tls guide

* list supported mechanisms early

* list formatting

* autobuilder

* DOCSP-18691 (#55)

* improved landing page

* DOCSP-18738 (#54)

* changed _id heading name

Co-authored-by: kyuan-mongodb <[email protected]>

Author: terakilobyte

snooty.toml

@@ -13,6 +13,6 @@ intersphinx = [
 
 [constants]
 docs-branch = "master" # always set this to the docs branch (i.e. master, 1.7, 1.8, etc.)
-version = "v1.7.0" # always set this to the driver branch (i.e. v1.7.0, v1.8.0, etc.)
+version = "v1.7.2" # always set this to the driver branch (i.e. v1.7.0, v1.8.0, etc.)
 example = "https://raw.githubusercontent.com/mongodb/docs-golang/{+docs-branch+}/source/includes/usage-examples/code-snippets"
 api = "https://pkg.go.dev/go.mongodb.org/mongo-driver@{+version+}"

source/fundamentals.txt

@@ -26,3 +26,12 @@ Fundamentals
   /fundamentals/gridfs
   /fundamentals/logging
   /fundamentals/monitoring
+
+The Fundamentals section explains how to perform the following tasks
+using the Go driver:
+
+- :doc:`Connect to MongoDB </fundamentals/connection>`
+- :doc:`How the Driver Uses Context </fundamentals/context>`
+- :doc:`Authenticate with MongoDB </fundamentals/auth>`
+- :doc:`Read from and Write to MongoDB </fundamentals/crud>`
+- :doc:`Work with BSON </fundamentals/bson>`

source/fundamentals/auth.txt

@@ -24,27 +24,35 @@ authentication mechanism, see our :doc:`Connection Guide </fundamentals/connecti
 Supported Mechanisms
 --------------------
 
+The Go driver supports the following authentication mechanisms:
+
+* :ref:`SCRAM-SHA-256 <go_sha_256>`
+* :ref:`SCRAM-SHA-1 <go_sha_1>`
+* :ref:`MONGODB-CR <go_mongodb_cr>`
+* :ref:`MongoDB-AWS <go_mongodb_aws>`
+* :ref:`X.509 <go_x509>`
+
 The Go Driver establishes a connection with an authentication mechanism
-through a `Client <https://pkg.go.dev/go.mongodb.org/[email protected]/mongo#Client>`__
+through a `Client <{+api+}/mongo#Client>`__
 type. The ``Client`` type specifies the mechanism and credentials to use
-as connection options in a `Credential <https://pkg.go.dev/go.mongodb.org/[email protected]/mongo/options#Credential>`__
+as connection options in a `Credential <{+api+}/mongo/options#Credential>`__
 type . To configure these options, pass a ``Credential`` type to the
-`SetAuth() <https://pkg.go.dev/go.mongodb.org/mongo[email protected]/mongo/options#ClientOptions.SetAuth>`__ 
-function of the `ClientOptions <https://pkg.go.dev/go.mongodb.org/[email protected]/mongo/options#ClientOptions>`__
-type. 
+`SetAuth() <{+api+}/mongo/options#ClientOptions.SetAuth>`__
+function of the `ClientOptions <{+api+}/mongo/options#ClientOptions>`__
+type.
 
 The following sections demonstrate this process with the five
-mechanisms the MongoDB Community Edition supports. 
+mechanisms the MongoDB Community Edition supports.
 
 Example Conventions
 ~~~~~~~~~~~~~~~~~~~
 
-Each authentication mechanism contains the following placeholders: 
+Each authentication mechanism contains the following placeholders:
 
 * ``username`` - Your MongoDB username
 * ``password`` - Your MongoDB user's password
 * ``hostname`` - Your MongoDB servers network address, accessible by
-  your client 
+  your client
 * ``port`` - Your MongoDB servers port number
 * ``authenticationDb`` - Your MongoDB database that contains the user's
   authentication data. If you omit this option, the driver uses the
@@ -67,8 +75,8 @@ mechanisms depending on what MongoDB versions your server supports:
      - Versions
 
    * - ``SCRAM-SHA-256``
-     - MongoDB 4.0 and later   
-   
+     - MongoDB 4.0 and later
+
    * - ``SCRAM-SHA-1``
      - MongoDB 3.0, 3.2, 3.4, and 3.6
 
@@ -94,6 +102,8 @@ For more information on the challenge-response (CR) and salted
 challenge-response authentication mechanisms (SCRAM) that MongoDB supports,
 see the :manual:`SCRAM </core/security-scram/>` section of the server manual.
 
+.. _go_sha_256:
+
 ``SCRAM-SHA-256``
 ~~~~~~~~~~~~~~~~~
 
@@ -107,7 +117,7 @@ see the :manual:`SCRAM </core/security-scram/>` section of the server manual.
 algorithm, to authenticate your user.
 
 To specify the ``SCRAM-SHA-256`` authentication mechanism, assign the
-``AuthMechanism`` option the value ``"SCRAM-SHA-256"``:  
+``AuthMechanism`` option the value ``"SCRAM-SHA-256"``:
 
 .. code-block:: go
    :emphasize-lines: 2
@@ -120,10 +130,11 @@ To specify the ``SCRAM-SHA-256`` authentication mechanism, assign the
    }
    clientOpts := options.Client().ApplyURI("mongodb://<hostname>:<port>").
       SetAuth(credential)
-   
+
    client, err := mongo.Connect(context.TODO(), clientOpts)
 
 .. _scram-sha-1-auth-mechanism:
+.. _go_sha_1:
 
 ``SCRAM-SHA-1``
 ~~~~~~~~~~~~~~~
@@ -138,7 +149,7 @@ username and password, encrypted with the ``SHA-1`` algorithm, to authenticate
 your user.
 
 To specify the ``SCRAM-SHA-1`` authentication mechanism, assign the
-``AuthMechanism`` option the value ``"SCRAM-SHA-1"``:  
+``AuthMechanism`` option the value ``"SCRAM-SHA-1"``:
 
 .. code-block:: go
    :emphasize-lines: 2
@@ -154,6 +165,8 @@ To specify the ``SCRAM-SHA-1`` authentication mechanism, assign the
 
    client, err := mongo.Connect(context.TODO(), clientOpts)
 
+.. _go_mongodb_cr:
+
 ``MONGODB-CR``
 ~~~~~~~~~~~~~~
 
@@ -165,6 +178,8 @@ username and password to authenticate your user.
    This authentication mechanism was deprecated starting in MongoDB 3.6
    and is no longer supported as of MongoDB 4.0.
 
+.. _go_mongodb_aws:
+
 ``MONGODB-AWS``
 ~~~~~~~~~~~~~~~
 
@@ -203,7 +218,7 @@ following:
    _ = awsIAMClient
 
 If you need to specify an AWS session token, use the temporary
-credentials returned from an assume role request. 
+credentials returned from an assume role request.
 
 To use temporary credentials, assign the ``AuthMechanismProperties``
 option the value of your ``sessionToken``:
@@ -224,6 +239,8 @@ option the value of your ``sessionToken``:
    assumeRoleClient, err := mongo.Connect(context.TODO(),
       options.Client().SetAuth(assumeRoleCredential))
 
+.. _go_x509:
+
 ``X.509``
 ~~~~~~~~~
 
@@ -258,6 +275,7 @@ following:
 
    clientOpts := options.Client().ApplyURI(uri).SetAuth(credential)
 
-For more information on configuring your application to use
-certificates as well as TLS/SSL options, see our
-:doc:`TLS/SSL guide </fundamentals/connection/tls>`.
+..
+  For more information on configuring your application to use
+  certificates as well as TLS/SSL options, see our
+  :doc:`TLS/SSL guide </fundamentals/connection/tls>`.

source/fundamentals/bson.txt

@@ -1,6 +1,6 @@
-=================
-Working with BSON
-=================
+==============
+Work with BSON
+==============
 
 .. default-domain:: mongodb
 
@@ -15,7 +15,7 @@ Overview
 
 In this guide, you can learn about how the Go Driver handles conversions
 between BSON and Go values. The process of converting a Go value to
-BSON is called **marshalling**, while the reverse process is called **unmarshalling**. 
+BSON is called **marshalling**, while the reverse process is called **unmarshalling**.
 
 You should read this guide if you want to learn more about how the Go Driver
 represents BSON data or need to adjust default marshalling
@@ -39,19 +39,18 @@ The following example demonstrates how to construct a query filter using the
 than 100:
 
 .. code-block:: go
-   
+
    filter := bson.D{{"quantity", bson.D{{"$gt", 100}}}}
 
 For more information on how the Go Driver handles BSON data, see the
-`bson package API documentation
-<https://pkg.go.dev/go.mongodb.org/mongo-driver/bson>`_.
+`bson package API documentation <{+api+}/bson>`__.
 
 Struct Tags
 -----------
 
 In Go, a **struct** is a collection of data fields with declared data
 types. The Go Driver can marshal/unmarshal structs and other native Go
-types to/from BSON using a `configurable codec system <https://pkg.go.dev/go.mongodb.org/mongo-driver/bson/bsoncodec>`_.
+types to/from BSON using a `configurable codec system <{+api+}/bson/bsoncodec>`_.
 
 You can modify the default marshalling and unmarshalling behavior of the Go Driver using
 **struct tags**, which are optional pieces of metadata attached to
@@ -79,11 +78,11 @@ use with the Go Driver:
 
    * - ``truncate``
      - If the field type is a non-float numeric type, BSON doubles
-       unmarshalled into that field will be trucated at the decimal point.
+       unmarshalled into that field will be truncated at the decimal point.
 
    * - ``inline``
      - If the field type is a struct or map field, the field will be
-       "flattened" when marshalling and "un-flattened" when unmarshalling.
+       flattened when marshalling and unflattened when unmarshalling.
 
 Without additional instruction from struct tags, the Go
 Driver will marshal structs using the following rules:
@@ -101,7 +100,7 @@ Driver will marshal structs using the following rules:
    value.
 
 #. When unmarshalling, the Go Driver follows `these D/M type mappings
-   <https://pkg.go.dev/go.mongodb.org/mongo-driver/bson#hdr-Native_Go_Types>`_
+   <{+api+}/bson#hdr-Native_Go_Types>`_
    for fields of type ``interface{}``. The driver unmarshals BSON documents
    unmarshalled into an ``interface{}`` field as a ``D`` type.
 
@@ -120,7 +119,7 @@ Driver will marshal structs using the following rules:
          	City   string
          	State  string
          }
-                  
+
          type Student struct {
          	FirstName string  `bson:"first_name,omitempty"`
          	LastName  string  `bson:"last_name,omitempty"`
@@ -138,8 +137,8 @@ Driver will marshal structs using the following rules:
 
       .. code-block:: json
          :copyable: false
-      
-         { 
+
+         {
            "_id" : ObjectId("..."),
            "first_name" : "Arthur",
            "street" : "1 Lakewood Way",
@@ -149,7 +148,7 @@ Driver will marshal structs using the following rules:
          }
 
       In this example, struct tags make the driver:
-      
+
       - Set custom BSON field names such as ``first_name``
       - Omit the empty ``LastName`` field
       - Flatten the nested struct and bring all fields up to the top
@@ -170,7 +169,7 @@ Driver will marshal structs using the following rules:
          	City   string
          	State  string
          }
-                  
+
          type Student struct {
          	FirstName string
          	LastName  string
@@ -188,8 +187,8 @@ Driver will marshal structs using the following rules:
 
       .. code-block:: json
          :copyable: false
-      
-         { 
+
+         {
            "_id" : ObjectId("..."),
            "firstname" : "Arthur",
            "lastname" : "",
@@ -200,9 +199,9 @@ Driver will marshal structs using the following rules:
                       },
            "age" : 8
          }
-         
+
       Without struct tags, the driver:
-      
+
       - Sets the lowercase of the struct fields as the BSON field names
       - Includes an empty ``lastname`` field
       - Stores the ``Address`` field as a nested value
@@ -219,12 +218,12 @@ The ``Decode()`` method returns an ``error`` type which
 contains one of the following values:
 
 - ``nil`` if a document matched your query, and there were no errors
-  retrieving and unmarshalling the document. 
+  retrieving and unmarshalling the document.
 - If the driver retrieved your document but could not unmarshal your result, the
   ``Decode()`` method returns the unmarshalling error.
 - If there was an error retrieving your document during execution of the
   ``FindOne()`` method, the error propagates to the ``Decode()`` method and
-  the ``Decode()`` method returns the error. 
+  the ``Decode()`` method returns the error.
 
 When used on the ``SingleResult`` type returned by the ``FindOne()``
 method, ``Decode()`` can also return the ``ErrNoDocuments`` error if no
@@ -235,7 +234,7 @@ method to unmarshal and read the result of a simple ``FindOne()``
 operation:
 
 .. code-block:: go
-   
+
    coll := client.Database("school").Collection("students")
    filter := bson.D{{"age", 8}}
 
@@ -248,21 +247,21 @@ operation:
 The output of the preceding code should look like this:
 
 .. code-block:: none
-   
+
    [{_id ObjectID("...")} {first_name Arthur} {street 1 Fern Way} {city Elwood City} {state PA} {age 8}]
 
 The ``Cursor`` type also uses the ``All()`` method, which unmarshals all
 documents stored in the cursor into an array at the same time.
 
 The ``bson`` package includes a family of
 ``Marshal()`` and ``Unmarshal()`` methods that work with BSON-encoded data
-of ``[]byte`` type. 
+of ``[]byte`` type.
 
 The following code demonstrates how you can unmarshal BSON back into a
 user-defined struct by using methods from the ``bson`` package:
 
 .. code-block:: go
-   
+
    type Item struct {
       Category string
       Quantity int32
@@ -279,21 +278,20 @@ user-defined struct by using methods from the ``bson`` package:
 The output of the preceding code should look like this:
 
 .. code-block:: none
-   
+
    Unmarshalled Struct:
    {Category:plate Quantity:6}
 
 .. note::
-   
+
    You can use the ``Raw`` type to retrieve elements from a BSON
    document byte slice without unmarshalling it to a Go value. This can
    be useful if you need to look up individual elements without
    unmarshalling the entire BSON document.
 
 For more information on the marshalling and unmarshalling methods used with the
-``Cursor`` type, see the `Cursor API documentation
-<https://pkg.go.dev/go.mongodb.org/[email protected]/mongo#Cursor>`_
+``Cursor`` type, see the `Cursor API documentation <{+api+}/mongo#Cursor>`__
 
 For more information on the marshalling and unmarshalling methods in the
 ``bson`` package, see the `bson API documentation
-<https://pkg.go.dev/go.mongodb.org/[email protected]/bson#hdr-Marshalling_and_Unmarshalling>`_
+<{+api+}/bson#hdr-Marshalling_and_Unmarshalling>`_