Merge pull request #6 from onebeyond/jsdocs

Autogenerated documentation

.github/workflows/deploy-documentation.yml

@@ -0,0 +1,59 @@
+name: Deploy documentation
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions: read-all
+
+jobs:
+  deploy-documentation:
+    name: Deploy documentation
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: 🔐 Harden Runner
+        uses: step-security/harden-runner@63c24ba6bd7ba022e95695ff85de572c04a18142 # v2.7.0
+        with:
+          egress-policy: audit
+          # disable-sudo: true
+          # egress-policy: block
+          # allowed-endpoints: >
+          #   api.github.com:443
+          #   api.osv.dev:443
+          #   api.securityscorecards.dev:443
+          #   fulcio.sigstore.dev:443
+          #   github.com:443
+          #   oss-fuzz-build-logs.storage.googleapis.com:443
+          #   rekor.sigstore.dev:443
+          #   tuf-repo-cdn.sigstore.dev:443
+          #   www.bestpractices.dev:443
+
+      - name: ⚙️ Checkout code
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        with:
+          persist-credentials: false
+
+      - name: ⚙️ Setup Node.js
+        uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1
+        with:
+          node-version: 20
+
+      - name: ⚙️ Install dependencies
+        run: npm clean-install
+
+      - name: 🔎 Verify the integrity of provenance attestations and registry signatures for installed dependencies
+        run: npm audit signatures
+
+      - name: ⚙️ Build
+        run: npm run docs:build
+
+      - name: 🚀 Push
+        uses: JamesIves/github-pages-deploy-action@65b5dfd4f5bcd3a7403bbc2959c144256167464e # v4.5.0
+        with:
+          branch: gh-pages
+          folder: ./docs
+          token: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -11,4 +11,7 @@ node_modules/
 .eslintcache
 
 # dotenv environment variables file
-.env*
+.env*
+
+# Auto-generated documentation
+docs/

README.md

@@ -1,14 +1,62 @@
-# agnostic-cms-harmonizer
-Library to manage the communication with any CMS agnostic to the user
+# Agnostic CMS harmonizer
+
+Library to handle communication with different CMSs in a user-agnostic way.
 
 ## Contribute
 
-#### Testing
+In order to contribute to this project, you need to follow the next steps:
+
+### Requirements
+
+- [contentful requirements](https://www.contentful.com/developers/docs/tutorials/cli/import-and-export/#requirements)
+- If you don't want to install the contentful CLI you can use the `npx` command to run it without installing it globally, as it's an optional dependency.
+
+### Contentful
+
+1. You have to create a space in contentful to run the tests.
+2. Following the instructions [here](https://www.contentful.com/developers/docs/references/authentication/#the-content-delivery-and-preview-api) to create an API key.
+
+### Environment variables
+
+Create a `.env` file in the root of the project with the following content:
+
+```bash 
+CONTENTFUL_ACCESS_TOKEN=your_access_token
+CONTENTFUL_ENVIRONMENT=your_environment
+CONTENTFUL_SPACE=your_space
+CONTENTFUL_ENTRY=your_entry
+```
+
+### Import dummy content to your space
 
-###### e2e
+To run the `e2e` tests you need to be authenticated in your contentful account and [import](https://www.contentful.com/developers/docs/tutorials/cli/import-and-export/#importing-content) the dummy content into the space you created before. The content you need to import is located at `__tests__/exports/contentful/agnostic-cms-harmonizer_space.json` and should not be updated.
 
-For being able to run the `e2e` tests you would need to **import the Contentful space** [following this steps](https://www.contentful.com/developers/docs/tutorials/cli/import-and-export/). The exported space is located at `__tests__/exports/contentful/agnostic-cms-harmonizer_space.json` and should not be updated. There is also a config file provided in case you need to export your space for any reason `./__tests__/exports/contentful/config.json`
+To log in to your contentful account run the following command and follow the instructions in the terminal:
 
 ```bash
+# If you have the contenful-cli installed globally
+contenful login
+
+# If you don't have the contenful-cli installed globally
+npx contentful-cli login
+```
+
+To import the dummy content run the following command:
+
+```bash
+# If you have the contenful-cli installed globally
+contentful space import --content-file __tests__/exports/contentful/agnostic-cms-harmonizer_space.json --space-id <your-contentful-space-id>
+
+# If you don't have the contenful-cli installed globally
+npx contentful-cli space import --content-file __tests__/exports/contentful/agnostic-cms-harmonizer_space.json --space-id <your-contentful-space-id>
+```
+
+There is also a config file provided in case you need to [export](https://www.contentful.com/developers/docs/tutorials/cli/import-and-export/#exporting-content) your space's content for any reason `./__tests__/exports/contentful/config.json`. You just need to change the `spaceId` and `environmentId` variables locally and run the following command:
+
+```bash
+# If you have the contenful-cli installed globally
+contentful space export --config ./__tests__/exports/contentful/config.json
+
+# If you don't have the contenful-cli installed globally
 npx contentful-cli space export --config ./__tests__/exports/contentful/config.json
-```
+```

__tests__/e2e/cms/contentful.test.ts

@@ -1,6 +1,7 @@
 import { config as configDotenv } from 'dotenv';
 configDotenv();
 
+
 import { Contentful } from '../../../src/cms/contentful';
 
 describe('contentful', () => {

__tests__/exports/contentful/config.json

@@ -1,6 +1,6 @@
 {
-  "spaceId": "804ocb5nrt21",
-  "environmentId": "master",
+  "spaceId": "<your-space-id>",
+  "environmentId": "<your-environment-id>",
   "exportDir": "./__tests__/exports/contentful",
   "saveFile": true,
   "contentFile": "agnostic-cms-harmonizer_space.json",