[ios] Add inline examples in documentation (#7337)

2 files changed, 70 insertions, 0 deletions

diff --git a/platform/ios/scripts/add-examples-to-docs.js b/platform/ios/scripts/add-examples-to-docs.js
new file mode 100644
index 0000000000..7be755e2c6
--- /dev/null
+++ b/platform/ios/scripts/add-examples-to-docs.js
@@ -0,0 +1,65 @@
+'use strict';
+
+const fs = require('fs');
+
+const examples = fs.readFileSync(`${__dirname}/../test/MGLDocumentationExampleTests.swift`, 'utf8');
+
+// Regex extracts the following block
+// /*---BEGIN EXAMPLE: MGLStyleSource---*/
+// /* Frontmatter to describe the example */
+// let sampleCode: String?
+// /*---END EXAMPLE---*/
+//
+// into the following regex groups:
+// 1 (token): " MGLStyleSource"
+// 2 (frontmatter): "/* Frontmatter to describe the example */"
+// 3 (sample code): "let sampleCode: String?"
+const exampleRegex = /\/\*---BEGIN EXAMPLE:(.*)---\*\/\s*(\/\*+[\s\S]*?\*+\/)?([\s\S]*?)\/\*---END EXAMPLE---\*\//gm;
+
+var path = `${process.env.TARGET_BUILD_DIR}/${process.env.PUBLIC_HEADERS_FOLDER_PATH}`;
+
+console.log("Installing examples...");
+
+var match;
+while ((match = exampleRegex.exec(examples)) !== null) {
+  const token = match[1].trim();
+  const className = token.split('.')[0];
+
+  const frontmatter = (match[2] || '')
+    .replace(/\/\*+/g, '') // Remove block comment /**
+    .replace(/\*+\//g, '') // Remove block comment end */
+    .trim()
+    .replace(/\n {8,9}/g, '\n'); // Remove leading whitespace (8-9 spaces incl block comment)
+
+  const exampleCode = match[3]
+    .trim()
+    .replace(/\n {8}/g, '\n'); // Remove leading whitespace (8 spaces)
+
+  // Generate example text
+  var exampleText = "### Example\n\n";
+  if (frontmatter.length > 0) {
+    exampleText += `${frontmatter}\n\n`;
+  }
+  exampleText += "```swift\n" + exampleCode + "\n```";
+  exampleText = exampleText.replace(/\n/g, '\n ');
+
+  const placeholderRegex = new RegExp(`<!--EXAMPLE: ${token}-->`);
+
+  // check if file exists at path
+  const filename = `${path}/${className}.h`;
+
+  if (fs.existsSync(filename)) {
+    const file = fs.readFileSync(filename, 'utf8');
+    // Check for example placeholder in file & update file if found
+    if (placeholderRegex.test(file)) {
+      console.log("Updating example:", filename);
+      fs.writeFileSync(filename, file.replace(placeholderRegex, exampleText));
+    } else if (file.indexOf(exampleText) === -1) {
+      console.log(`Placeholder "${token}" missing:`, filename);
+    } else {
+      console.log(`Example "${token}" already replaced.`);
+    }
+  } else if (token !== "ExampleToken") {
+    console.log("Error file doesn't exist:", filename);
+  }
+}
diff --git a/platform/ios/scripts/document.sh b/platform/ios/scripts/document.sh
index fddf5abb0f..78eb5121eb 100755
--- a/platform/ios/scripts/document.sh
+++ b/platform/ios/scripts/document.sh
@@ -35,11 +35,16 @@ cp platform/ios/screenshot.png "${OUTPUT}"
 DEFAULT_THEME="platform/darwin/docs/theme"
 THEME=${JAZZY_THEME:-$DEFAULT_THEME}
 
+DEFAULT_FRAMEWORK_PATH="build/ios/pkg/dynamic/Mapbox.framework"
+FRAMEWORK_PATH=${FRAMEWORK_PATH:-$DEFAULT_FRAMEWORK_PATH}
+
 jazzy \
     --config platform/ios/jazzy.yml \
     --sdk iphonesimulator \
     --github-file-prefix https://github.com/mapbox/mapbox-gl-native/tree/${BRANCH} \
     --module-version ${SHORT_VERSION} \
+    --framework-root ${FRAMEWORK_PATH} \
+    --umbrella-header "${FRAMEWORK_PATH}/Headers/Mapbox.h" \
     --readme ${README} \
     --documentation="platform/ios/docs/Info.plist Keys.md" \
     --root-url https://www.mapbox.com/ios-sdk/api/${RELEASE_VERSION}/ \