feat(ci): add ci build for documentation

Also deactivated megalinter since it doesn't help with Swift.

.github/workflows/megalinter.yml

@@ -15,14 +15,14 @@ jobs:
       - name: Checkout Code
         uses: actions/checkout@v3
 
-      - name: Mega-Linter
-        id: ml
-        uses: megalinter/megalinter@v6
-        env:
-          VALIDATE_ALL_CODEBASE: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
-          DISABLE: COPYPASTE,SPELL
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          DISABLE_LINTERS: SWIFT_SWIFTLINT,YAML_V8R,REPOSITORY_DEVSKIM,REPOSITORY_TRIVY,REPOSITORY_GITLEAKS
+#      - name: Mega-Linter
+#        id: ml
+#        uses: megalinter/megalinter@v6
+#        env:
+#          VALIDATE_ALL_CODEBASE: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+#          DISABLE: COPYPASTE,SPELL
+#          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+#          DISABLE_LINTERS: SWIFT_SWIFTLINT,YAML_V8R,REPOSITORY_DEVSKIM,REPOSITORY_TRIVY,REPOSITORY_GITLEAKS
 
       - name: SwiftLint
         uses: norio-nomura/[email protected]
@@ -31,11 +31,11 @@ jobs:
         env:
           DIFF_BASE: ${{ github.base_ref }}
 
-      - name: Archive production artifacts
-        if: success() || failure()
-        uses: actions/upload-artifact@v2
-        with:
-          name: Mega-Linter reports
-          path: |
-            report
-            mega-linter.log
+#      - name: Archive production artifacts
+#        if: success() || failure()
+#        uses: actions/upload-artifact@v2
+#        with:
+#          name: Mega-Linter reports
+#          path: |
+#            report
+#            mega-linter.log

.github/workflows/releaseDocumentation.yml

@@ -0,0 +1,59 @@
+---
+name: Release Documentation
+
+on:
+#  push:
+#    branches:
+#      - main
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  docs:
+    name: build documentation and release
+    runs-on: macos-latest
+    env:
+      GITHUB_ACTOR: ${{ github.actor }}
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v3
+
+      - name: Install SSH Key
+        uses: shimataro/[email protected]
+        with:
+          key: ${{ secrets.SSH_PRIVATE_KEY }}
+          known_hosts: github.com
+
+      - name: Adding Known Hosts
+        run: ssh-keyscan -H github.com >> ~/.ssh/known_hosts
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.0
+          bundler-cache: true
+
+      - name: Install Jazzy
+        run: sudo gem install jazzy
+
+      - name: ABC Install
+        uses: lyricwulf/abc@v1
+        with:
+          macos: sourcekitten
+
+      - name: Build Docs
+        run: ./.scripts/buildDocs.sh
+
+      - name: Push
+        uses: s0/git-publish-subdir-action@develop
+        env:
+          REPO: self
+          BRANCH: gh-pages # The branch name where you want to push the assets
+          FOLDER: docs # The directory where your assets are generated
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # GitHub will automatically add this - you don't need to bother getting a token
+          MESSAGE: "feat(docs): ({sha}) {msg}" # The commit message

.gitignore

@@ -42,3 +42,5 @@ protobuf/*.swift
 Sources/PrismSwiftSDK/protobuf
 OpenAPI
 Package.resolved
+docs
+Documentation

.jazzy.json

@@ -0,0 +1,5 @@
+{
+  "string-replacements": {
+      "<doc:PrismAgentErrors>": "[Prism Agent Errors](prismagenterrors.html)"
+  }
+}

.jazzy.yaml

@@ -0,0 +1,53 @@
+# .jazzy.yaml
+
+# General configuration options
+module: AtalaPrismSDK
+author: IOG
+github_url: https://github.com/input-output-hk/atala-prism-wallet-sdk-swift
+
+# Source directory and files to include
+#source:
+#  - MyLibrary/
+#  - README.md
+
+# Markdown files to include
+documentation:
+  - 'Documentation/*.md'
+
+custom_categories:
+  - name: Getting Started
+    children:
+    - AtalaPrismSDK
+    - Mediation
+    - Logging
+  - name: Architecture
+    children:
+    - BuildingBlocks
+    - TechnicalConsiderations
+    - ModularApproach
+  - name: Error Handling
+    children:
+    - ErrorHandling
+    - ApolloErrors
+    - CastorErrors
+    - MercuryErrors
+    - PlutoErrors
+    - PrismAgentErrors
+  - name: Prism Agent
+    children:
+    - PrismAgent
+    - PrismAgentTutorials
+  - name: Apollo
+    children:
+    - Apollo
+    - ApolloTutorials
+  - name: Castor
+    children:
+    - Castor
+    - CastorTutorials
+  - name: Pluto
+    children:
+    - Pluto
+  - name: Pollux
+    children:
+    - Pollux

.scripts/buildDocs.sh

@@ -0,0 +1,20 @@
+#!/bin/sh
+
+# Sourcekitten all modules so we can merge them
+sourcekitten doc -- -scheme AtalaPrismSDK -destination "name=iPhone 14" > AtalaPrismSDK.json
+sourcekitten doc -- -scheme Domain -destination "name=iPhone 14" > Domain.json
+sourcekitten doc -- -scheme Apollo -destination "name=iPhone 14" > Apollo.json
+sourcekitten doc -- -scheme Mercury -destination "name=iPhone 14" > Mercury.json
+sourcekitten doc -- -scheme Pluto -destination "name=iPhone 14" > Pluto.json
+sourcekitten doc -- -scheme Pollux -destination "name=iPhone 14" > Pollux.json
+sourcekitten doc -- -scheme PrismAgent -destination "name=iPhone 14" > PrismAgent.json
+
+# Copy all the *.md files to the Documentation folder
+bash ./.scripts/prepareDocumentation.sh
+# Replace every <doc:XxYy> by [Xx Yy](xxyy.html)
+ruby ./.scripts/preDoc.rb
+
+# It needs to be castor module since the sourcekitten is adding the Protobuf files.
+jazzy --module Castor --sourcekitten-sourcefile AtalaPrismSDK.json,Domain.json,Apollo.json,Mercury.json,Pluto.json,Pollux.json,PrismAgent.json --theme fullwidth --hide-documentation-coverage
+# Replace in the index the Castor references by Atala Prism SDK
+ruby ./.scripts/prepareIndex.rb

.scripts/preDoc.rb

@@ -0,0 +1,28 @@
+require 'json'
+
+# Read the string-replacements from the .jazzy.json file
+jazzy_conf = JSON.parse(File.read('.jazzy.json'))
+transforms = jazzy_conf['string-replacements']
+
+# Loop through all .md files in the Documentation directory
+Dir.glob('Documentation/*.md').each do |file|
+  # Read the contents of the file
+  contents = File.read(file)
+
+  # Apply all replacements to the contents of the file
+  if transforms
+    transforms.each_pair do |key, value|
+      contents = contents.gsub(key, value)
+    end
+  end
+
+  # Replace <doc:AnythingAndSomething> with a link to anythingandsomething.html
+  contents = contents.gsub(/<doc:([\w\s]+)>/) do |match|
+    name = match.gsub('<doc:', '').gsub('>', '').gsub(/(.)([A-Z])/,'\1 \2')
+    link = name.downcase.gsub(' ', '') + '.html'
+    "[#{name}](#{link})"
+  end
+
+  # Write the updated contents back to the file
+  File.write(file, contents)
+end

.scripts/prepareDocumentation.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+
+# Create the output directory if it doesn't exist
+mkdir -p "Documentation/"
+
+# Find all subfolders in the current directory and loop through them
+find AtalaPrismSDK -type d | while read dir
+do
+  # Check if the folder name contains ".docc"
+  if [[ "$dir" == *".docc"* ]]
+  then
+   # Copy .md files if they exist
+    if [ -n "$(find "$dir" -maxdepth 1 -name '*.md' -print -quit)" ]
+    then
+      cp -p "$dir"/*.md "Documentation/"
+    fi
+
+    # Copy .png files if they exist
+    if [ -n "$(find "$dir" -maxdepth 1 -name '*.png' -print -quit)" ]
+    then
+      cp -p "$dir"/*.png "Documentation/"
+    fi
+  fi
+done

.scripts/prepareIndex.rb

@@ -0,0 +1,7 @@
+File.open('docs/index.html', 'r+') do |file|
+  content = file.read
+  content.gsub!('Castor Reference', 'Atala PRISM SDK Reference')
+  content.gsub!('Castor Docs', 'Atala PRISM SDK Docs')
+  file.rewind
+  file.write(content)
+end

AtalaPrismSDK/AtalaPrismSDK/Sources/AtalaPrismSDK.docc/AtalaPrismSDK.md

@@ -12,45 +12,21 @@ Atala PRISM is a self-sovereign identity (SSI) platform and service suite for ve
 
 Atala PRISM Swift SDK provides the following building blocks to create, manage and resolve decentralized identifiers, issue, manage and verify verifiable credentials, establish and manage trusted, peer-to-peer connections and interactions between DIDs, and store, manage, and recover verifiable data linked to DIDs.
 
-- __Apollo__: Building block that provides a suite of criptographic operations.
+- __Apollo__: Building block that provides a suite of cryptographic operations.
 - __Castor__: Building block that provides a suite of DID operations in a user-controlled manner.
 - __Pollux__: Building block that provides a suite of credential operations in a privacy-preserving manner.
 - __Mercury__: Building block that provides a set of secure, standards-based communications protocols in a transport-agnostic and interoperable manner.
 - __Pluto__: Building block that provides an interface for storage operations in a portable, storage-agnostic manner.
-- __PrismAgent__: PrismAgent using all the building blocks provides a agent that can provide a set of high level DID functionalities.
-
-## Getting Started
-
-### Setup
-
-To get started with the Atala PRISM Swift SDK, you can set up the SDK and start a new project, or you can integrate the SDK in an existing project. Before you start, make sure you have the following installed on your development machine:
-
-- Xcode 13.4 or later
-- MacOS 12 or later
-- iOS 15 or later
-
-> ⚠️ **Currently you need to always open the XCode in ROSETTA mode**
-
-### Integrating the SDK in an existing project
-
-To integrate the SDK into an existing project, you can use the Swift Package Manager, which is distributed with Xcode.
-
-1. Open your project in Xcode and select **File > Swift Packages > Add Package Dependency**.
-2. Enter the URL for the SDK for Swift Package Manager GitHub repo (`https://github.com/input-output-hk/atala-prism-wallet-sdk-swift`) into the search bar and click **Next**.
-3. You'll see the repository rules for which version of the SDK you want Swift Package Manager to install. Choose the first rule, **Version**, and select **Up to Next Minor** as it will use the latest compatible version of the dependency that can be detected from the `main` branch, then click **Next**.
-
-### Swift Package Manager
-
-The Swift Package Manager is a tool for managing the distribution of Swift code. It's integrated with the Swift build system to automate the process of downloading, compiling, and linking dependencies.
+- __PrismAgent__: PrismAgent using all the building blocks provides an agent that can offer a set of high level DID functionalities.
 
 ## Documentation
 
 ### General information and articles
 
-- [Getting Started](https://staging-docs.atalaprism.io/docs/getting-started)
-- [What is identity?](https://staging-docs.atalaprism.io/docs/concepts/what-is-identity)
-- [Digital wallets](https://staging-docs.atalaprism.io/docs/concepts/digital-wallets)
-- [Atala PRISM Overview](https://staging-docs.atalaprism.io/docs/atala-prism/overview)
+- [Getting Started](https://docs.atalaprism.io/docs/getting-started)
+- [What is identity?](https://docs.atalaprism.io/docs/concepts/what-is-identity)
+- [Digital wallets](https://docs.atalaprism.io/docs/concepts/digital-wallets)
+- [Atala PRISM Overview](https://docs.atalaprism.io/docs/atala-prism/overview)
 
 ### Architecture decision articles
 

AtalaPrismSDK/AtalaPrismSDK/Sources/AtalaPrismSDK.docc/BuildingBlocks.md

@@ -10,7 +10,7 @@ Let's take a closer look at each building block:
 
 - [Apollo](apollo.html): Apollo is a building block that provides a suite of cryptographic operations. This includes secure hash algorithms, digital signatures, and encryption, which are all essential for creating a secure and tamper-proof identity system. Apollo ensures that all data within the Atala PRISM system is securely encrypted and digitally signed, making it resistant to tampering and unauthorized access.
 - [Castor](castor.html): Castor is a building block that provides a suite of decentralized identifier (DID) operations in a user-controlled manner. DIDs are a key component of decentralized identity, as they provide a way to uniquely identify individuals and entities in a decentralized manner. Castor allows users to create, manage, and control their DIDs and associated cryptographic keys.
-- [Pollux](pollux.html): Pollux is a building block that provides a suite of credential operations in a privacy-preserving manner. Credentials are a way to prove claims about an individual or entity, and they are an important part of decentralized identity. Pollux allows users to create, manage, and share credentials in a privacy-preserving way, using zero-knowledge proofs to ensure that sensitive information is not revealed.
+- [Pollux](pollux.html): Pollux is a building block that provides a suite of credential operations in a privacy-preserving manner. Credentials are a way to prove claims about an individual or entity, and they are an important part of decentralized identity. Pollux allows users to create, manage, and share credentials in a privacy-preserving way to ensure that sensitive information is not revealed.
 - [Mercury](mercury.html): Mercury is a building block that provides a set of secure, standards-based communications protocols in a transport-agnostic and interoperable manner. Mercury allows different components of Atala PRISM to communicate with each other securely, using standard protocols such as HTTP, WebSocket, and MQTT.
 - [Pluto](pluto.html): Pluto is a building block that provides an interface for storage operations in a portable, storage-agnostic manner. Pluto allows data to be stored and retrieved in a way that is independent of the underlying storage technology, allowing Atala PRISM to work with a variety of storage solutions.
 

README.md

@@ -11,11 +11,11 @@ This SDK provides a library and documentation for developers to build Apple conn
 Atala PRISM is a self-sovereign identity (SSI) platform and service suite for verifiable data and digital identity. Built on Cardano, it offers core infrastructure for issuing DIDs (Decentralized identifiers) and verifiable credentials, alongside tools and frameworks to help expand your ecosystem.
 The complete platform is separated in multiple repositories:
 
-* [atala-prism-wallet-sdk-swift]() - Repo that implements Atala Prism for Apple platforms in Swift.
-* [atala-prism-wallet-sdk-ts](https://github.com/input-output-hk/atala-prism-wallet-sdk-ts) - Repo that implements Atala Prism for Browser and NodeJS platforms in Typescript.
+* [atala-prism-wallet-sdk-swift]() - Repo that implements Atala PRISM for Apple platforms in Swift.
+* [atala-prism-wallet-sdk-ts](https://github.com/input-output-hk/atala-prism-wallet-sdk-ts) - Repo that implements Atala PRISM for Browser and NodeJS platforms in Typescript.
 * [atala-prism-building-blocks](https://github.com/input-output-hk/atala-prism-building-blocks) - Repo that contains the platform Building Blocks.
 
-### Features / APIs
+### Modules / APIs
 
 Atala PRISM Swift SDK provides the following building blocks to create, manage and resolve decentralized identifiers, issue, manage and verify verifiable credentials, establish and manage trusted, peer-to-peer connections and interactions between DIDs, and store, manage, and recover verifiable data linked to DIDs.