Generates documentation with Apple's DocC for a target that supports both iOS and macOS.

docc.sh

#!/bin/bash

#######################################################################
# Generates documentation for a target, for example a Swift package,
# that supports both iOS and macOS.
#
# The script is designed to be placed in the root of a Swift package.
# Change the paths as needed if your project structure is different.
#
# In order for DocC to annotate all symbols with the platforms
# (e.g. iOS and macOS) that they are available on, you must either
# manually annotate the symbols in your code with @available(...)
# or add an Info.plist to your .docc bundle with the default
# availability like shown below.
# 
# <?xml version="1.0" encoding="UTF-8"?>
# <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
# <plist version="1.0">
# <dict>
#   <key>CDAppleDefaultAvailability</key>
#   <dict>
#     <key>Example</key>
#     <array>
#       <dict>
#         <key>name</key>
#         <string>macOS</string>
#         <key>version</key>
#         <string>12.0</string>
#       </dict>
#       <dict>
#         <key>name</key>
#         <string>iOS</string>
#         <key>version</key>
#         <string>16.0</string>
#       </dict>
#     </array>
#   </dict>
# </dict>
# </plist>
#
# Apple also have an example Info.plist here:
# https://github.com/apple/swift-docc/blob/main/Tests/SwiftDocCTests/Test%20Bundles/TestBundle.docc/Info.plist#L25
#
# Thanks to Franklin Schrans for providing the guidance needed in
# order for me to put this script together.
# https://mastodon.social/@franklin_/109761834575324416
#####################################################################

SCHEME="Example" # Remember to change this
DOCC_BUNDLE_PATH="Sources/Example/Example.docc" # Remember to change this

# Paths used in the script.
DERIVED_DATA_DIR=".deriveddata"
BUILD_DIR=".build"
SYMBOL_GRAPHS_DIR="${BUILD_DIR}/symbol-graphs"
SYMBOL_GRAPHS_DIR_IOS="${SYMBOL_GRAPHS_DIR}/ios"
SYMBOL_GRAPHS_DIR_MACOS="${SYMBOL_GRAPHS_DIR}/macos"
DOCCARCHIVE_PATH="${PWD}/${SCHEME}.doccarchive"

# Generate *.symbols.json file for iOS.
mkdir -p "${SYMBOL_GRAPHS_DIR_IOS}"
xcodebuild build \
  -scheme "${SCHEME}" \
  -destination "generic/platform=iOS" \
  -derivedDataPath "${DERIVED_DATA_DIR}" \
  OTHER_SWIFT_FLAGS="-emit-symbol-graph -emit-symbol-graph-dir ${SYMBOL_GRAPHS_DIR_IOS}"

# Generate *.symbols.json file for macOS.
mkdir -p "${SYMBOL_GRAPHS_DIR_MACOS}"
xcodebuild build \
  -scheme "${SCHEME}" \
  -destination "generic/platform=macOS" \
  -derivedDataPath "${DERIVED_DATA_DIR}" \
  OTHER_SWIFT_FLAGS="-emit-symbol-graph -emit-symbol-graph-dir ${SYMBOL_GRAPHS_DIR_MACOS}"

# Create a .doccarchive from the symbols.
$(xcrun --find docc) convert "${DOCC_BUNDLE_PATH}" \
  --index \
  --fallback-display-name "${SCHEME}" \
  --fallback-bundle-identifier "${SCHEME}" \
  --fallback-bundle-version 0 \
  --output-dir "${DOCCARCHIVE_PATH}" \
  --additional-symbol-graph-dir "${SYMBOL_GRAPHS_DIR}"

# Clean up.
rm -rf "${DERIVED_DATA_DIR}"
rm -rf "${BUILD_DIR}"