First step towards DocC iOS docs (#867)

Co-authored-by: Ovidiu Voda <ovi.voda@gmail.com>

.github/workflows/gh-pages-docc.yml

@@ -0,0 +1,24 @@
+name: gh-pages-docc
+
+on:
+  workflow_dispatch:
+
+jobs:
+  gh-pages-docc:
+    defaults:
+      run:
+        working-directory: platform/ios
+    runs-on: [self-hosted, macOS, ARM64]
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v3
+
+      - name: Generate documentation
+        run: make ios-docs
+
+      - name: Deploy 🚀
+        uses: JamesIves/github-pages-deploy-action@v4.4.1
+        with:
+          branch: gh-pages
+          folder: platform/ios/build/ios/static-docs
+          target-folder: docs/ios/docc/

platform/ios/Makefile

@@ -258,6 +258,14 @@ darwin-check-public-symbols:
 
 endif
 
+ios-docs: $(IOS_PROJ_PATH) style-code
+	$(IOS_XCODEBUILD_SIM) docbuild -scheme CI
+
+ios-docs-static: ios-docs
+	$(xcrun --find docc) process-archive transform-for-static-hosting \
+		$(IOS_OUTPUT_PATH)/Debug-iphonesimulator/Mapbox.doccarchive \
+		--output-path $(IOS_OUTPUT_PATH)/static-docs
+
 #### macOS targets ############################################################
 
 ifeq ($(HOST_PLATFORM), macos)
@@ -291,7 +299,7 @@ macos: $(MACOS_PROJ_PATH)
 	set -o pipefail && $(MACOS_XCODEBUILD) -scheme 'CI' build $(XCPRETTY)
 
 .PHONY: xproj
-xproj: $(MACOS_PROJ_PATH)
+xproj: $(MACOS_PROJ_PATH) style-code
 	xed $(MACOS_WORK_PATH)
 
 #  make macos-test

platform/ios/platform/ios/CONTRIBUTING.md

@@ -58,7 +58,17 @@ make iframework BUILDTYPE=Release
 
 The products of these build commands can be found in the `build/ios/pkg` folder at the base of the repository.
 
-#### Generating Documentation
+## Documentation
+
+We are moving away from the legacy Jazzy documentation towards Apple's documentation generator [DocC](https://developer.apple.com/documentation/docc). DocC has great Xcode intergration. See the [open issues](https://github.com/maplibre/maplibre-gl-native/issues?q=is%3Aissue+is%3Aopen+label%3Aios+label%3Adocumentation) if you want to help.
+
+- For a general introduction to DocC, including for example a demonstration of the custom Markdown that DocC uses that allows for cross-linking, see this WWDC video: https://developer.apple.com/videos/play/wwdc2021/10166/
+- For instructions of how to write a tutorial in DooC format: https://developer.apple.com/documentation/docc/building-an-interactive-tutorial
+- For instructions of how to write supplemental documentation: https://www.swift.org/documentation/docc/adding-supplemental-content-to-a-documentation-catalog
+
+The most convenient way to generate the DocC based documentation locally is using Xcode by going to Product > Build Documentation. A new window will pop up ([screenshot](https://user-images.githubusercontent.com/649392/219097391-710a8421-df82-4b5e-864f-e3317cea0b8e.png)).
+
+### Jazzy Documentation
 
 The code samples in the header files & [iOS API Documentation](https://maplibre.org/maplibre-gl-native/ios/api/) are generated by a unit test.
 

platform/ios/platform/ios/Documentation.docc/Documentation.md

@@ -0,0 +1,5 @@
+# ``Mapbox``
+
+@Metadata {
+    @DisplayName("MapLibre GL Native")
+}