From f59c2bdd6b5f2c0a7bcae7c85226064fd08c25b8 Mon Sep 17 00:00:00 2001 From: Goncalo-FradeIOHK Date: Tue, 28 Feb 2023 22:22:10 +0000 Subject: [PATCH] feat(ci): add ci build for documentation Also deactivated megalinter since it doesn't help with Swift. --- .github/workflows/megalinter.yml | 32 +++++----- .github/workflows/releaseDocumentation.yml | 59 +++++++++++++++++++ .gitignore | 2 + .jazzy.json | 5 ++ .jazzy.yaml | 53 +++++++++++++++++ .scripts/buildDocs.sh | 20 +++++++ .scripts/preDoc.rb | 28 +++++++++ .scripts/prepareDocumentation.sh | 24 ++++++++ .scripts/prepareIndex.rb | 7 +++ .../AtalaPrismSDK.docc/AtalaPrismSDK.md | 36 ++--------- .../AtalaPrismSDK.docc/BuildingBlocks.md | 2 +- Mintfile | 2 - README.md | 6 +- 13 files changed, 224 insertions(+), 52 deletions(-) create mode 100644 .github/workflows/releaseDocumentation.yml create mode 100644 .jazzy.json create mode 100644 .jazzy.yaml create mode 100755 .scripts/buildDocs.sh create mode 100644 .scripts/preDoc.rb create mode 100755 .scripts/prepareDocumentation.sh create mode 100644 .scripts/prepareIndex.rb delete mode 100644 Mintfile diff --git a/.github/workflows/megalinter.yml b/.github/workflows/megalinter.yml index 55afd2e4..24547489 100644 --- a/.github/workflows/megalinter.yml +++ b/.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/action-swiftlint@3.2.1 @@ -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 diff --git a/.github/workflows/releaseDocumentation.yml b/.github/workflows/releaseDocumentation.yml new file mode 100644 index 00000000..1fda00d3 --- /dev/null +++ b/.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/ssh-key-action@v2.3.0 + 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 diff --git a/.gitignore b/.gitignore index 69a60578..d4d6057b 100644 --- a/.gitignore +++ b/.gitignore @@ -42,3 +42,5 @@ protobuf/*.swift Sources/PrismSwiftSDK/protobuf OpenAPI Package.resolved +docs +Documentation diff --git a/.jazzy.json b/.jazzy.json new file mode 100644 index 00000000..d212d3b2 --- /dev/null +++ b/.jazzy.json @@ -0,0 +1,5 @@ +{ + "string-replacements": { + "": "[Prism Agent Errors](prismagenterrors.html)" + } +} diff --git a/.jazzy.yaml b/.jazzy.yaml new file mode 100644 index 00000000..1e956416 --- /dev/null +++ b/.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 diff --git a/.scripts/buildDocs.sh b/.scripts/buildDocs.sh new file mode 100755 index 00000000..c474ca47 --- /dev/null +++ b/.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 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 diff --git a/.scripts/preDoc.rb b/.scripts/preDoc.rb new file mode 100644 index 00000000..af08f6b1 --- /dev/null +++ b/.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 with a link to anythingandsomething.html + contents = contents.gsub(//) do |match| + name = match.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 diff --git a/.scripts/prepareDocumentation.sh b/.scripts/prepareDocumentation.sh new file mode 100755 index 00000000..d9326d53 --- /dev/null +++ b/.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 diff --git a/.scripts/prepareIndex.rb b/.scripts/prepareIndex.rb new file mode 100644 index 00000000..c67afe45 --- /dev/null +++ b/.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 diff --git a/AtalaPrismSDK/AtalaPrismSDK/Sources/AtalaPrismSDK.docc/AtalaPrismSDK.md b/AtalaPrismSDK/AtalaPrismSDK/Sources/AtalaPrismSDK.docc/AtalaPrismSDK.md index 762fdfbd..ad01735c 100644 --- a/AtalaPrismSDK/AtalaPrismSDK/Sources/AtalaPrismSDK.docc/AtalaPrismSDK.md +++ b/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 diff --git a/AtalaPrismSDK/AtalaPrismSDK/Sources/AtalaPrismSDK.docc/BuildingBlocks.md b/AtalaPrismSDK/AtalaPrismSDK/Sources/AtalaPrismSDK.docc/BuildingBlocks.md index 52ee0fbe..a17849ee 100644 --- a/AtalaPrismSDK/AtalaPrismSDK/Sources/AtalaPrismSDK.docc/BuildingBlocks.md +++ b/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. diff --git a/Mintfile b/Mintfile deleted file mode 100644 index 66e22cde..00000000 --- a/Mintfile +++ /dev/null @@ -1,2 +0,0 @@ -realm/SwiftLint@0.43.1 -nicklockwood/SwiftFormat@0.47.13 diff --git a/README.md b/README.md index 1425ae47..eaa84140 100644 --- a/README.md +++ b/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.