Merge pull request #357 from fractal-analytics-platform/docs

Publish mkdocs docs on github pages

Author: tcompa

.github/workflows/documentation.yaml

@@ -0,0 +1,42 @@
+name: docs
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+
+  docs:
+    name: "Deploy docs"
+    runs-on: ubuntu-latest
+    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REQUIREMENTS: docs/doc-requirements.txt
+
+  docs-build:
+    name: "Test docs build"
+    runs-on: ubuntu-latest
+    if: ${{ github.event_name != 'push' || github.ref != 'refs/heads/main' }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+          cache: pip
+
+      - name: Install dependencies
+        run: python -m pip install -r docs/doc-requirements.txt
+
+      - name: MKDocs build
+        run: mkdocs build --config-file mkdocs.yml --strict

.gitignore

@@ -13,3 +13,5 @@ node_modules
 coverage*/
 .nyc_output
 playwright-report/
+venv
+site

docs/changelog.md

@@ -0,0 +1 @@
+--8<-- "CHANGELOG.md"

docs/dependencies.md

@@ -0,0 +1,12 @@
+# Dependencies
+
+**in progress**
+
+Here are the main external dependencies and where/how they are used:
+
+* ajv
+* datatables
+* dompurify
+* semver
+* jose
+* marked

docs/development/dependencies.md

@@ -0,0 +1,3 @@
+# Documentation
+
+**in progress**

docs/development/docs.md

@@ -0,0 +1,10 @@
+# Development
+
+Here are some useful details for `fractal-web` developments:
+
+* [Code-base structure](structure.md)
+* [External dependencies](dependencies.md)
+* [Tests](tests.md)
+* [Documentation](docs.md)
+* [Precommit](precommit.md)
+* [JSON Schema component](json_schemas.md)

docs/development/index.md

@@ -0,0 +1,3 @@
+# JSON Schemas for WorkflowTask arguments
+
+**in progress**

docs/development/json_schemas.md

@@ -0,0 +1,19 @@
+## pre-commit setup
+
+In your local folder, create a file `.git/hooks/pre-commit` with the following content
+
+```bash
+#!/bin/bash
+npm run pre-commit
+RESULT=$?
+[ $RESULT -ne 0 ] && exit 1
+exit 0
+```
+
+and make this file executable (`chmod +x .git/hooks/pre-commit`).
+
+In this way, `npm run pre-commit` will run before every commit. This script is
+defined in `package.json`, and points to
+[`lint-staged`](https://github.com/okonet/lint-staged). The configuration is
+written in `.lintstagedrc.json`, and it lists the checks to perform on each
+kind of file (e.g. `eslint` and then `prettier`).

docs/development/precommit.md

@@ -79,7 +79,7 @@ is serving the application. This request, with the attached cookies, is then use
 
 The following image provides an overview for the reader of the described architecture.
 
-![proxy-architecture.png](media/proxy-architecture.png)
+![proxy-architecture.png](../media/proxy-architecture.png)
 
 To avoid duplicating the logic of each fractal-server endpoint and simplify the error handling, a special Svelte route has been setup to act like a transparent proxy: `src/routes/api/[...path]/+server.js`. This is one of the suggested way to handle a different backend [according to Svelte Kit FAQ](https://kit.svelte.dev/docs/faq#how-do-i-use-x-with-sveltekit-how-do-i-use-a-different-backend-api-server).