SWIFT-1113 Include BSON symbols in driver docs (#607)

kmahar · web-flow · commit cc4329767f04 · 2021-02-18T12:00:19.000-05:00
diff --git a/.jazzy.yml b/.jazzy.yml
@@ -16,6 +16,7 @@ custom_categories:
   - name: Core Types
     children:
       - MongoClient
+      - EventLoopBoundMongoClient
       - MongoClientOptions
       - MongoDatabase
       - MongoDatabaseOptions
@@ -139,6 +140,7 @@ custom_categories:
       - CollectionType
       - CreateCollectionOptions
       - DropCollectionOptions
+      - RenameCollectionOptions
       
   - name: Sessions & Transactions
     children:
diff --git a/etc/docs-main.md b/etc/docs-main.md
@@ -7,4 +7,4 @@ The MongoDB Swift driver contains two modules:
 
 See [here](https://mongodb.github.io/mongo-swift-driver/docs) for documentation of other versions of the driver.
 
-The driver relies on our [official Swift BSON library](https://github.com/mongodb/swift-bson), with API documentation available [here](https://mongodb.github.io/swift-bson).
+The driver relies on our [official Swift BSON library](https://github.com/mongodb/swift-bson). For convenience, we have merged the BSON documentation in with the driver documentation on this website, but you can also view it separately [here](https://mongodb.github.io/swift-bson).
diff --git a/etc/generate-docs.sh b/etc/generate-docs.sh
@@ -18,14 +18,26 @@ version=${1}
 # Ensure version is non-empty
 [ ! -z "${version}" ] || { echo "ERROR: Missing version string"; exit 1; }
 
+# ensure we have fresh build data for the docs generation process
+rm -rf .build
+
+# obtain BSON version from Package.resolved
+bson_version="$(python3 etc/get_bson_version.py)"
+
+git clone --depth 1 --branch "v${bson_version}" https://github.com/mongodb/swift-bson
+working_dir=${PWD}
+cd swift-bson
+sourcekitten doc --spm --module-name SwiftBSON > ${working_dir}/bson-docs.json
+cd $working_dir
+
 jazzy_args=(--clean
             --github-file-prefix https://github.com/mongodb/mongo-swift-driver/tree/v${version} 
             --module-version "${version}")
 
 # Generate MongoSwift docs
 sourcekitten doc --spm --module-name MongoSwift > mongoswift-docs.json
 args=("${jazzy_args[@]}"  --output "docs-temp/MongoSwift" --module "MongoSwift" --config ".jazzy.yml" 
-        --sourcekitten-sourcefile mongoswift-docs.json
+        --sourcekitten-sourcefile mongoswift-docs.json,bson-docs.json 
         --root-url "https://mongodb.github.io/mongo-swift-driver/docs/MongoSwift/")
 jazzy "${args[@]}"
 
@@ -37,12 +49,26 @@ python3 etc/filter_sourcekitten_output.py
 sourcekitten doc --spm --module-name MongoSwiftSync > mongoswiftsync-docs.json
 
 args=("${jazzy_args[@]}"  --output "docs-temp/MongoSwiftSync" --module "MongoSwiftSync" --config ".jazzy.yml" 
-        --sourcekitten-sourcefile mongoswift-filtered.json,mongoswiftsync-docs.json
+        --sourcekitten-sourcefile mongoswift-filtered.json,mongoswiftsync-docs.json,bson-docs.json 
         --root-url "https://mongodb.github.io/mongo-swift-driver/docs/MongoSwiftSync/")
 jazzy "${args[@]}"
 
+rm -rf swift-bson
 rm mongoswift-docs.json
 rm mongoswift-filtered.json
 rm mongoswiftsync-docs.json
+rm bson-docs.json
 
 echo '<html><head><meta http-equiv="refresh" content="0; url=MongoSwift/index.html" /></head></html>' > docs-temp/index.html
+
+# we can only pass a single GitHub file prefix above, so we need to correct the BSON file paths throughout the docs.
+
+# Jazzy generates the links for each file by taking the base path we provide above as --github-file-prefix and tacking on
+#  the path of each file relative to the project's root directory. since we check out swift-bson from the root of the driver,
+# all of the generated URLs for BSON symbols are of the form
+# ....mongo-swift-driver/tree/v[driver version]/swift-bson/...
+# Here we replace all occurrences of this with the correct GitHub root URL, swift-bson/tree/v[bson version].
+# note: we have to pass -print0 to `find` and pass -0 to `xargs` because some of the file names have spaces in them, which by
+# default xargs will treat as a delimiter.
+find docs-temp -name "*.html" -print0 | \
+xargs -0 etc/sed.sh -i "s/mongo-swift-driver\/tree\/v${version}\/swift-bson/swift-bson\/tree\/v${bson_version}/"
diff --git a/etc/get_bson_version.py b/etc/get_bson_version.py
@@ -0,0 +1,6 @@
+import json
+
+with open('Package.resolved', 'r') as f:
+    data = json.load(f)
+    bson_data = next(d for d in data['object']['pins'] if d['package'] == 'swift-bson')
+    print(bson_data['state']['version'])

Original file line number	Diff line number	Diff line change
`@@ -7,4 +7,4 @@ The MongoDB Swift driver contains two modules:`
`7`	`7`
`8`	`8`	`See [here](https://mongodb.github.io/mongo-swift-driver/docs) for documentation of other versions of the driver.`
`9`	`9`
`10`		`-The driver relies on our [official Swift BSON library](https://github.com/mongodb/swift-bson), with API documentation available [here](https://mongodb.github.io/swift-bson).`
	`10`	`+The driver relies on our [official Swift BSON library](https://github.com/mongodb/swift-bson). For convenience, we have merged the BSON documentation in with the driver documentation on this website, but you can also view it separately [here](https://mongodb.github.io/swift-bson).`