diff --git a/build/build_doc.xml b/build/build_doc.xml deleted file mode 100644 index 399917ab02..0000000000 --- a/build/build_doc.xml +++ /dev/null @@ -1,111 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/generate_docs.sh b/docs/generate_docs.sh index e35826dc46..2bd3f82d5a 100755 --- a/docs/generate_docs.sh +++ b/docs/generate_docs.sh @@ -4,6 +4,273 @@ # Run this script from the root of the repo to generate docs for the libraries in this workspace. # The generated docs are placed under the 'build/artifacts/doc' folder. # +# This script uses DocC (Apple's Documentation Compiler) to generate documentation. +# Requires Xcode 13+ to be installed. +# + +set -e + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +NC='\033[0m' # No Color + +# Ensure we run from the repository root (parent of docs/) +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" +cd "$REPO_ROOT" + +# Configuration +LIBS_DIR="libs" +OUTPUT_DIR="build/artifacts/doc" +DERIVED_DATA_DIR="build/DerivedData" +DESTINATION="generic/platform=iOS Simulator" +# GitHub Pages base path (forcedotcom.github.io/SalesforceMobileSDK-iOS/Documentation/...) +HOSTING_BASE="/SalesforceMobileSDK-iOS/Documentation" + +# Libraries to document +LIBRARIES=( + "SalesforceSDKCommon" + "SalesforceAnalytics" + "SalesforceSDKCore" + "SmartStore" + "MobileSync" +) + +echo -e "${GREEN}Starting DocC documentation generation...${NC}" + +# Clean and create output directory +rm -rf "$OUTPUT_DIR" +mkdir -p "$OUTPUT_DIR" + +# Build documentation for each library +for lib in "${LIBRARIES[@]}"; do + echo -e "\n${YELLOW}Building documentation for $lib...${NC}" + + PROJECT_PATH="$LIBS_DIR/$lib/$lib.xcodeproj" + + if [ ! -d "$PROJECT_PATH" ]; then + echo -e "${RED}Error: Project not found at $PROJECT_PATH${NC}" + continue + fi + + # Build documentation using xcodebuild docbuild + xcodebuild docbuild \ + -scheme "$lib" \ + -project "$PROJECT_PATH" \ + -destination "$DESTINATION" \ + -derivedDataPath "$DERIVED_DATA_DIR" \ + | grep -E "Build Succeeded|error:|warning:|note:" || true + + # Find the generated .doccarchive (may be under Debug-iphonesimulator or similar) + DOCCARCHIVE=$(find "$DERIVED_DATA_DIR" -name "$lib.doccarchive" -type d | head -n 1) + + if [ -z "$DOCCARCHIVE" ]; then + echo -e "${RED}Warning: Documentation archive not found for $lib${NC}" + continue + fi + + echo "doc archive -> $DOCCARCHIVE" + + # Convert to static HTML for GitHub Pages hosting + echo "Converting to static HTML..." + $(xcrun --find docc) process-archive transform-for-static-hosting \ + "$DOCCARCHIVE" \ + --output-path "$OUTPUT_DIR/$lib" \ + --hosting-base-path "$HOSTING_BASE/$lib" + + # DocC does not apply hosting-base-path to the root index.html, so fix asset + # URLs for subdirectory hosting (local test and GitHub Pages). + LIB_INDEX="$OUTPUT_DIR/$lib/index.html" + if [ -f "$LIB_INDEX" ]; then + BASE_PREFIX="$HOSTING_BASE/$lib" + sed -i.bak "s|var baseUrl = \"/\"|var baseUrl = \"$BASE_PREFIX/\"|" "$LIB_INDEX" + sed -i.bak "s|src=\"/|src=\"$BASE_PREFIX/|g" "$LIB_INDEX" + sed -i.bak "s|href=\"/|href=\"$BASE_PREFIX/|g" "$LIB_INDEX" + rm -f "$LIB_INDEX.bak" + fi + + # DocC renderer fetches theme-settings.json; 404 causes "page not found". Add minimal file if missing. + if [ ! -f "$OUTPUT_DIR/$lib/theme-settings.json" ]; then + echo '{"theme":{}}' > "$OUTPUT_DIR/$lib/theme-settings.json" + fi + + echo -e "${GREEN}✓ Documentation for $lib generated successfully${NC}" +done + +# Generate static HTML fallback for each library (no JavaScript required) +echo -e "\n${YELLOW}Generating static HTML fallbacks...${NC}" +for lib in "${LIBRARIES[@]}"; do + MODULE_ID=$(echo "$lib" | tr '[:upper:]' '[:lower:]') + MODULE_JSON="$OUTPUT_DIR/$lib/data/documentation/$MODULE_ID.json" + if [ ! -f "$MODULE_JSON" ] && [ -d "$OUTPUT_DIR/$lib/data/documentation" ]; then + # DocC may use a different module name (e.g. from bundle); use first .json in data/documentation + MODULE_JSON=$(find "$OUTPUT_DIR/$lib/data/documentation" -maxdepth 1 -name "*.json" -type f 2>/dev/null | head -n 1) + fi + STATIC_HTML="$OUTPUT_DIR/$lib/static-index.html" + if [ -n "$MODULE_JSON" ] && [ -f "$MODULE_JSON" ]; then + python3 - "$MODULE_JSON" "$lib" "$STATIC_HTML" "$HOSTING_BASE" << 'PYTHON_SCRIPT' || true +import json, sys, html +from pathlib import Path +mod_path = Path(sys.argv[1]) +lib_name = sys.argv[2] +out_path = Path(sys.argv[3]) +hosting_base = sys.argv[4] if len(sys.argv) > 4 else "/Documentation" +try: + data = json.loads(mod_path.read_text(encoding="utf-8")) +except Exception: + data = {} +refs = data.get("references") or {} +def abstract_text(ref): + if not isinstance(ref, dict): + return "" + blocks = ref.get("abstract") or [] + return " ".join(b.get("text", "") for b in blocks if isinstance(b, dict)).strip() +def ref_title(r): + if not isinstance(r, dict): + return "" + name = r.get("title") + if name: + return str(name) + nt = r.get("navigatorTitle") + if isinstance(nt, list) and nt: + return str(nt[0].get("text") or nt[0].get("kind", "")) + if isinstance(nt, str): + return nt + return "" +sections_html = [] +for sec in data.get("topicSections") or []: + title = sec.get("title", "") or "" + ids = sec.get("identifiers") or [] + if not ids: + continue + items = [] + for doc_id in ids: + r = refs.get(doc_id) or {} + name = ref_title(r) or "(symbol)" + abstract = abstract_text(r) + url = (r.get("url") or "").strip() + if url and not url.startswith("/"): + url = "/" + url + # Link to DocC-generated topic page (same structure as swift.org: .../documentation/{module}/{symbol}/) + if url: + topic_url = f"{hosting_base}/{lib_name}/documentation{url}".rstrip("/") + "/" + link = f'{html.escape(name)}' + else: + link = html.escape(name) + items.append(f"
  • {link}" + (f" — {html.escape(abstract)}" if abstract else "") + "
    • ") + sections_html.append(f"

    {html.escape(title)}

    ") +base = f"{hosting_base}/{lib_name}" +# Link to the real DocC module overview page (same URL structure as swift.org/documentation) +module_overview_url = f"{base}/documentation/{mod_path.stem}/" +body = f""" + + + + +{html.escape(lib_name)} — API Reference + + + + +

    {html.escape(lib_name)}

    +

    Browse full documentation Single-page app

    +

    Symbols below link to the generated topic pages. Use “Browse full documentation” for the full DocC experience.

    +{"".join(sections_html)} +
    +

    ← Documentation index

    + +""" +out_path.write_text(body, encoding="utf-8") +PYTHON_SCRIPT + fi + # Replace the DocC root index with the static one so the library URL shows content without JS + BASE_PREFIX="$HOSTING_BASE/$lib" + if [ -f "$OUTPUT_DIR/$lib/index.html" ] && [ -f "$STATIC_HTML" ]; then + mv "$OUTPUT_DIR/$lib/index.html" "$OUTPUT_DIR/$lib/docc-app.html" + mv "$STATIC_HTML" "$OUTPUT_DIR/$lib/index.html" + fi + # Ensure docc-app.html (or index.html if static wasn't generated) has correct asset paths for subdirectory + for candidate in "$OUTPUT_DIR/$lib/docc-app.html" "$OUTPUT_DIR/$lib/index.html"; do + if [ -f "$candidate" ] && grep -q 'src="/js/' "$candidate" 2>/dev/null; then + sed -i.bak "s|var baseUrl = \"/\"|var baseUrl = \"$BASE_PREFIX/\"|" "$candidate" + sed -i.bak "s|src=\"/|src=\"$BASE_PREFIX/|g" "$candidate" + sed -i.bak "s|href=\"/|href=\"$BASE_PREFIX/|g" "$candidate" + rm -f "${candidate}.bak" + fi + done +done + +# Create an index page for easy navigation (Swift DocC–style: Documentation home with clear links) +get_lib_description() { + case "$1" in + SalesforceSDKCommon) echo "Common utilities and components shared across the SDK" ;; + SalesforceAnalytics) echo "Analytics and instrumentation framework" ;; + SalesforceSDKCore) echo "Core SDK functionality including authentication and networking" ;; + SmartStore) echo "Encrypted offline storage solution" ;; + MobileSync) echo "Data synchronization framework" ;; + *) echo "API reference" ;; + esac +} +{ + echo '' + echo '' + echo '' + echo ' ' + echo ' ' + echo ' Salesforce Mobile SDK for iOS — Documentation' + echo ' ' + echo '' + echo '' + echo '

    Documentation

    ' + echo '

    Salesforce Mobile SDK for iOS. Choose a library:

    ' + echo ' ' + echo '
    ' + echo '

    ' + echo ' GitHub repository' + echo '

    ' + echo '' + echo '' +} > "$OUTPUT_DIR/index.html" + +# Clean up derived data +# rm -rf "$DERIVED_DATA_DIR" + +echo -e "\n${GREEN}Documentation generation complete!${NC}" +echo -e "Documentation HTML files are available at: ${YELLOW}$OUTPUT_DIR${NC}" +echo -e "\nGenerated documentation structure:" +for lib in "${LIBRARIES[@]}"; do + echo -e " - $OUTPUT_DIR/$lib/" +done +echo -e " - $OUTPUT_DIR/index.html (navigation page)" -# Generates Obj-C library docs. -ant -buildfile build/build_doc.xml +echo -e "\n${YELLOW}Note:${NC} Documentation is generated for GitHub Pages at ${GREEN}${HOSTING_BASE}/${NC}" diff --git a/readme.md b/readme.md index ab04c4eb38..9b062aebb5 100644 --- a/readme.md +++ b/readme.md @@ -41,11 +41,11 @@ The Salesforce Mobile SDK provides the essential libraries for quickly building Documentation == -* [SalesforceSDKCommon Library Reference](http://forcedotcom.github.io/SalesforceMobileSDK-iOS/Documentation/SalesforceSDKCommon/html/index.html) -* [SalesforceAnalytics Library Reference](http://forcedotcom.github.io/SalesforceMobileSDK-iOS/Documentation/SalesforceAnalytics/html/index.html) -* [SalesforceSDKCore Library Reference](http://forcedotcom.github.io/SalesforceMobileSDK-iOS/Documentation/SalesforceSDKCore/html/index.html) -* [SmartStore Library Reference](http://forcedotcom.github.io/SalesforceMobileSDK-iOS/Documentation/SmartStore/html/index.html) -* [MobileSync Library Reference](http://forcedotcom.github.io/SalesforceMobileSDK-iOS/Documentation/MobileSync/html/index.html) +* [SalesforceSDKCommon Library Reference](http://forcedotcom.github.io/SalesforceMobileSDK-iOS/Documentation/SalesforceSDKCommon/documentation/salesforcesdkcommon/) +* [SalesforceAnalytics Library Reference](http://forcedotcom.github.io/SalesforceMobileSDK-iOS/Documentation/SalesforceAnalytics/documentation/salesforceanalytics/) +* [SalesforceSDKCore Library Reference](http://forcedotcom.github.io/SalesforceMobileSDK-iOS/Documentation/SalesforceSDKCore/documentation/salesforcesdkcore/) +* [SmartStore Library Reference](http://forcedotcom.github.io/SalesforceMobileSDK-iOS/Documentation/SmartStore/documentation/smartstore/) +* [MobileSync Library Reference](http://forcedotcom.github.io/SalesforceMobileSDK-iOS/Documentation/MobileSync/documentation/mobilesync/) * Salesforce Mobile SDK Development Guide -- [HTML](https://developer.salesforce.com/docs/atlas.en-us.mobile_sdk.meta/mobile_sdk/preface_intro.htm) * [Mobile SDK Trail](https://trailhead.salesforce.com/en/content/learn/trails/start-ios-appdev)