docs: implement versioning documentation (#10)

* docs: implement versioning documentation * chore: update documentation version dropdown position to left * docs: update README with documentation management and release document pipeline instructions * chore: format document for the README.md * docs: update README.md and the build_publish_docs pipeline * chore: update build_publish_docs.yml pipeline * chore: update build_publish_docs.yml pipeline
uncefact · Dec 23, 2024 · 3ef6fc5 · 3ef6fc5
1 parent 70abc69
commit 3ef6fc5
Show file tree

Hide file tree

Showing 18 changed files with 4,034 additions and 2,485 deletions.
diff --git a/.github/workflows/build_publish_docs.yml b/.github/workflows/build_publish_docs.yml
@@ -0,0 +1,51 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    name: Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    environment: github-pages
+
+    steps:
+      # Checkout repository code to access documentation files and source code
+      - uses: actions/checkout@v4
+
+      # Setup Node.js environment with caching to optimize dependency installation
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 21
+          cache: yarn
+
+      # Install all required Node.js packages and dependencies for documentation generation
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+        working-directory: documentation
+
+      # Build static documentation website with environment variables for proper URL configuration
+      - name: Build website
+        run: yarn build
+        env:
+          DOCS_BASE_URL: ${{ vars.DOCS_BASE_URL }}
+          DOCS_URL: ${{ vars.DOCS_URL }}
+        working-directory: documentation
+
+      # Deploy built documentation to gh-pages branch for GitHub Pages hosting
+      # Popular action to deploy to GitHub Pages:
+      # Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          # Build output to publish to the `gh-pages` branch:
+          publish_dir: ./documentation/build
+          # The following lines assign commit authorship to the official
+          # GH-Actions bot for deploys to `gh-pages` branch:
+          # https://github.com/actions/checkout/issues/13#issuecomment-724415212
+          # The GH actions bot is used by default if you didn't specify the two fields.
+          # You can swap them out with your own user credentials.
diff --git a/README.md b/README.md
@@ -223,3 +223,44 @@ docker run -d --env-file .env -p 3333:3333 \
 -e AWS_SECRET_ACCESS_KEY=YOUR_AWS_SECRET \
 storage-service:latest
 ```
+
+## Documentation
+
+The project uses Docusaurus for documentation management. Documentation versions are managed through a release script and automated pipeline.
+
+### Release Script
+
+The `scripts/release-doc.js` script automates the process of creating new documentation versions:
+
+- Reads the documentation version from `version.json`
+- Creates Docusaurus version using `docVersion` value from `version.json` file
+
+To manually create a new documentation version:
+
+```bash
+# Run the release script
+yarn release:doc
+```
+
+### Documentation Pipeline
+
+The documentation is automatically built and deployed using GitHub Actions through the `build_publish_docs.yml` pipeline. This pipeline:
+
+1. Triggers on:
+
+- Manual workflow dispatch
+- (TODO) Push to main branch once enabled
+
+2. Performs the following steps:
+
+- Checks out the repository
+- Sets up Node.js 18 with Yarn cache
+- Installs documentation dependencies
+- Builds the static documentation site
+- Deploys to GitHub Pages using gh-pages branch
+
+The pipeline uses environment variables for configuration:
+- `DOCS_BASE_URL`: Base URL for documentation hosting
+- `DOCS_URL`: Documentation site URL
+
+The built documentation is published to the `gh-pages` branch using the GitHub Actions bot.
diff --git a/documentation/docs/features/index.md b/documentation/docs/features/index.md
@@ -38,6 +38,21 @@ The service will respond similarly to the data below:
 }
 ```
 
+#### Request Payload
+
+| Field | Description | Required |
+|-------|-------------| -------- |
+| `bucket` | Name of the bucket where the data will be stored. | Yes |
+| `data` | The actual data to be stored, must be in JSON format. | Yes |
+
+#### Response Data
+
+| Field | Description |
+|-------|-------------|
+| `uri` | The link to the stored data. | 
+| `hash` | A hash of the data, used to verify your data hasn't been changed. |
+| `key` | The symmetric key used to decrypt the encrypted data. |
+
 ### Store Document
 - **Endpoint**: `/v1/documents`
 - **Method**: POST
@@ -66,6 +81,20 @@ The service will respond similarly to the data below:
 }
 ```
 
+#### Request Payload
+
+| Field | Description | Required |
+|-------|-------------| -------- |
+| `bucket` | Name of the bucket where the data will be stored. | Yes |
+| `data` | The actual data to be stored, must be in JSON format. | Yes |
+
+#### Response Data
+
+| Field | Description |
+|-------|-------------|
+| `uri` | The link to the stored data. | 
+| `hash` | A hash of the data, used to verify your data hasn't been changed. |
+
 ## Storage Providers
 
 - **Local Storage**: File system storage for development

diff --git a/documentation/docusaurus.config.ts b/documentation/docusaurus.config.ts
@@ -34,6 +34,8 @@ const config: Config = {
         docs: {
           sidebarPath: './sidebars.ts',
           editUrl: 'https://github.com/uncefact/project-identity-resolver/tree/next',
+          routeBasePath: 'docs',
+          includeCurrentVersion: false,
         },
         blog: false,
         theme: {
@@ -65,7 +67,12 @@ const config: Config = {
         src: 'img/logo.svg',
       },
       items: [
-        {to: '/docs/introduction', label: 'Introduction', position: 'right'},
+        {
+          type: 'docsVersionDropdown',
+          position: 'left',
+          dropdownActiveClassDisabled: true,
+        },
+        {to: '/docs/introduction/', label: 'Introduction', position: 'right'},
         {
           to: '/docs/getting-started/',
           label: 'Getting started',
@@ -93,7 +100,7 @@ const config: Config = {
           html: '<svg class="icon"><use xlink:href="#github"></use></svg><span class="menu-item-name">Github</span>',
           className: 'navbar-github-link',
           position: 'right',
-        },
+        }
       ],
     },
     prism: {

diff --git a/documentation/package.json b/documentation/package.json
@@ -1,6 +1,6 @@
 {
   "name": "documentation",
-  "version": "1.0.0-alpha",
+  "version": "1.0.0",
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",
@@ -15,9 +15,9 @@
     "typecheck": "tsc"
   },
   "dependencies": {
-    "@docusaurus/core": "3.4.0",
-    "@docusaurus/preset-classic": "3.4.0",
-    "@docusaurus/theme-mermaid": "^3.4.0",
+    "@docusaurus/core": "3.6.3",
+    "@docusaurus/preset-classic": "3.6.3",
+    "@docusaurus/theme-mermaid": "^3.6.3",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "docusaurus-plugin-sass": "^0.2.5",
@@ -27,9 +27,9 @@
     "sass": "^1.77.6"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.4.0",
-    "@docusaurus/tsconfig": "3.4.0",
-    "@docusaurus/types": "3.4.0",
+    "@docusaurus/module-type-aliases": "3.6.3",
+    "@docusaurus/tsconfig": "3.6.3",
+    "@docusaurus/types": "3.6.3",
     "typescript": "~5.2.2"
   },
   "browserslist": {

diff --git a/documentation/src/pages/index.tsx b/documentation/src/pages/index.tsx
@@ -30,8 +30,7 @@ function HomepageHero() {
 
 export default function Home() {
   return (
-    <Layout
-      description="A secure credential storage solution that complies with UNTP standards.">
+    <Layout>
       <main className="homepage-content">
         <HomepageHero/>
         <HomepageFeatures/>

diff --git a/documentation/versioned_docs/version-1.0.0/_disclaimer.mdx b/documentation/versioned_docs/version-1.0.0/_disclaimer.mdx
@@ -0,0 +1,3 @@
+:::info
+Please note that this content is under development and is not ready for implementation. This status message will be updated as content development progresses.
+:::
diff --git a/documentation/versioned_docs/version-1.0.0/features/index.md b/documentation/versioned_docs/version-1.0.0/features/index.md
@@ -0,0 +1,115 @@
+---
+sidebar_position: 4
+title: Features
+---
+
+import Disclaimer from './../_disclaimer.mdx';
+
+<Disclaimer />
+
+## API Endpoints
+
+### Store Credential
+- **Endpoint**: `/v1/credentials`
+- **Method**: POST
+- Stores encrypted credentials with optional ID
+- Returns URI, hash, and encryption key
+
+Test the service using `curl`:
+
+```bash
+curl -X POST http://localhost:3333/v1/credentials \
+-H "Content-Type: application/json" \
+-d '{
+  "bucket": "verifiable-credentials",
+  "data": {
+    "field1": "value1"
+  }
+}'
+```
+
+The service will respond similarly to the data below:
+
+```json
+{
+  "uri": "http://localhost:3333/v1/verifiable-credentials/e8b32169-582c-421a-a03f-5d1a7ac62d51.json",
+  "hash": "d6bb7b579925baa4fe1cec41152b6577003e6a9fde6850321e36ad4ac9b3f30a",
+  "key": "f3bee3dc18343aaab66d28fd70a03015d2ddbd5fd3b9ad38fff332c09014598d"
+}
+```
+
+#### Request Payload
+
+| Field | Description | Required |
+|-------|-------------| -------- |
+| `bucket` | Name of the bucket where the data will be stored. | Yes |
+| `data` | The actual data to be stored, must be in JSON format. | Yes |
+
+#### Response Data
+
+| Field | Description |
+|-------|-------------|
+| `uri` | The link to the stored data. | 
+| `hash` | A hash of the data, used to verify your data hasn't been changed. |
+| `key` | The symmetric key used to decrypt the encrypted data. |
+
+### Store Document
+- **Endpoint**: `/v1/documents`
+- **Method**: POST
+- Stores documents with computed hash
+- Returns URI and document hash
+
+Test the service using `curl`:
+
+```bash
+curl -X POST http://localhost:3333/v1/documents \
+-H "Content-Type: application/json" \
+-d '{
+  "bucket": "test-verifiable-credentials",
+  "data": {
+    "field1": "value1"
+  }
+}'
+```
+
+The service will respond similarly to the data below:
+
+```json
+{
+  "uri": "http://localhost:3333/v1/test-verifiable-credentials/2ad789c7-e513-4523-a826-ab59e1c423cd.json",
+  "hash": "d6bb7b579925baa4fe1cec41152b6577003e6a9fde6850321e36ad4ac9b3f30a"
+}
+```
+
+#### Request Payload
+
+| Field | Description | Required |
+|-------|-------------| -------- |
+| `bucket` | Name of the bucket where the data will be stored. | Yes |
+| `data` | The actual data to be stored, must be in JSON format. | Yes |
+
+#### Response Data
+
+| Field | Description |
+|-------|-------------|
+| `uri` | The link to the stored data. | 
+| `hash` | A hash of the data, used to verify your data hasn't been changed. |
+
+## Storage Providers
+
+- **Local Storage**: File system storage for development
+- **Google Cloud Storage**: GCP bucket storage for production
+- **Amazon S3**: AWS S3 bucket storage for production
+
+## Security Features
+
+### Cryptography
+- SHA-256 hash computation
+- AES-256-GCM encryption
+- Secure key management
+- Data integrity verification
+
+### Configuration Options
+- Flexible storage provider selection
+- Environment-based configuration
+- Secure credential management