feat(doc): Add user/dev/admin documentation

DIRACGrid · Dec 17, 2024 · a81b78a · a81b78a
1 parent dc93692
commit a81b78a
Show file tree

Hide file tree

Showing 28 changed files with 852 additions and 7,180 deletions.
diff --git a/.github/DISCUSSION_TEMPLATE/design-ideas.yaml b/.github/DISCUSSION_TEMPLATE/design-ideas.yaml
diff --git a/.github/DISCUSSION_TEMPLATE/user-personas-and-stories.yaml b/.github/DISCUSSION_TEMPLATE/user-personas-and-stories.yaml
@@ -4,7 +4,7 @@ body:
     attributes:
       value: >
         Develop a user persona and a story to capture the goals and tasks your users want to accomplish with diracx-web.
-        We are interested in understanding your needs and goals. Please focus on what you want to achieve rather than how you think it should be achieved.
+        We are interested in understanding your needs and goals. Please, first focus on what you want to achieve rather than how you think it should be achieved first.
         All ideas are welcome, and there are no wrong answers. We appreciate your honest feedback as it helps us improve the system to better meet your needs.
 
   - type: textarea
@@ -43,10 +43,27 @@ body:
     validations:
       required: true
 
+  - type: markdown
+    attributes:
+      value: |
+        From this point, you can optionally propose ideas of how it should be conceived, even if you technically do not know whether it is achievable.
+
   - type: textarea
-    id: additional-comments
+    id: design-solution
     attributes:
-      label: Additional Comments or Suggestions
-      description: "Share any other feedback, ideas, or suggestions that can help us understand your needs better."
-    validations:
-      required: false
+      label: Proposed Design Solution
+      description: |
+        Design proposal(s) can be submitted here.
+        Explain how your design solves the problem. Describe the design changes in details.
+      placeholder: "Describe your design solution..."
+
+  - type: markdown
+    attributes:
+      value: |
+        If possible, please attach an image representing a mockup or sketch of your design idea. Visual representations can help communicate your idea more clearly.
+
+  - type: markdown
+    attributes:
+      value: |
+        Once again, thank you for your contribution. Our team will review your design proposal(s) and provide feedback.
+
diff --git a/.github/workflows/deployment.yml b/.github/workflows/deployment.yml
@@ -74,7 +74,7 @@ jobs:
           cache: 'npm'
 
       - name: Build documentation
-        run: npm ci && npm --prefix packages/diracx-web-components run build-storybook
+        run: npm ci && npm --prefix packages/diracx-web-components run build-doc
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3

diff --git a/.github/workflows/gubbins-test.yml b/.github/workflows/gubbins-test.yml
@@ -1,4 +1,4 @@
-name: Gubbins extension tests
+name: Gubbins extension Tests
 
 on:
   push:
@@ -41,9 +41,64 @@ jobs:
         run: npm --prefix packages/extensions run ts-lint
 
   # ============================================================================#
-  # WARNING: In your CI/CD pipeline, you should remove the following job        #
+  # WARNING: In your CI/CD pipeline, you should remove the following jobs       #
   # ----------------------------------------------------------------------------#
-  prepare-gubbins-as-a-standalone:
+  # By default, the gubbins extension is part of a monorepo and uses a local    #
+  # version of `diracx-web-components`. This default setup is not               #
+  # representative of a standalone extension configuration. Here we want to     #
+  # closely mimic a standalone extension. To do so, we:                         #
+  # - Isolate the packages/extensions directory: Move its content to a new      #
+  #   repository or directory outside the monorepo.                             #
+  # - Update Configuration: Adjust relevant variables to align with a           #
+  #   standalone setup.                                                         #
+  prepare-gubbins-backend:
+    runs-on: ubuntu-latest
+    if: ${{ github.event_name != 'push' || github.repository == 'DIRACGrid/diracx-web' }}
+    steps:
+      - name: Clone source
+        run: |
+          cd ..
+          git clone https://github.com/DIRACGrid/diracx.git
+
+      - name: Where the magic happens (Move extensions to a temporary directory)
+        run: |
+          # We have to copy the code to another directory
+          # and make it a git repository by itself because otherwise the
+          # root in the pyproject to do not make sense once mounted
+          # in the containers.
+          cp -r ../diracx/extensions/gubbins /tmp/
+          sed -i 's@../..@.@g' /tmp/gubbins/pyproject.toml
+          sed -i 's@../../@@g' /tmp/gubbins/gubbins-*/pyproject.toml
+          git init /tmp/gubbins/
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: gubbins
+          path: /tmp/gubbins
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build and export service
+        uses: docker/build-push-action@v6
+        with:
+          context: ../diracx/extensions/containers/services
+          tags: gubbins/services:dev
+          outputs: type=docker,dest=/tmp/gubbins_services_image.tar
+          build-args: |
+            EXTRA_PACKAGES_TO_INSTALL=git+https://github.com/DIRACGrid/DIRAC.git@integration
+            EXTENSION_CUSTOM_SOURCES_TO_INSTALL=/bindmount/gubbins_db*.whl,/bindmount/gubbins_routers*.whl,/bindmount/gubbins_client*.whl
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: gubbins-services-img
+          path: /tmp/gubbins_services_image.tar
+
+  prepare-gubbins-frontend-as-a-standalone:
     runs-on: ubuntu-latest
     if: ${{ github.event_name != 'push' || github.repository == 'DIRACGrid/diracx-web' }}
     steps:
@@ -64,37 +119,39 @@ jobs:
 
       - name: Where the magic happens (Move extensions to a temporary directory)
         run: |
-          # Move the library package to the extensions directory
-          mv packages/diracx-web-components/*.tgz packages/extensions/diracx-web-components.tgz
           # Move the extensions to the temporary directory
-          mv packages/extensions /tmp/extensions
+          cp -r packages/extensions /tmp/gubbins-web
+          # Move the library package to the extensions directory
+          mv packages/diracx-web-components/*.tgz /tmp/gubbins-web/diracx-web-components.tgz
           # Update the package.json to point to the local diracx-web-components
-          jq '.dependencies["@dirac-grid/diracx-web-components"] = "file:./diracx-web-components.tgz"' /tmp/extensions/package.json > /tmp/extensions/package.temp.json
-          mv /tmp/extensions/package.temp.json /tmp/extensions/package.json
+          jq '.dependencies["@dirac-grid/diracx-web-components"] = "file:./diracx-web-components.tgz"' /tmp/gubbins-web/package.json > /tmp/gubbins-web/package.temp.json
+          mv /tmp/gubbins-web/package.temp.json /tmp/gubbins-web/package.json
           # Update the package.json to point to the correct postinstall script
-          jq '.scripts.postinstall = "node ./node_modules/@axa-fr/react-oidc/bin/copy-service-worker-files.mjs public"' /tmp/extensions/package.json > /tmp/extensions/package.temp.json
-          mv /tmp/extensions/package.temp.json /tmp/extensions/package.json
+          jq '.scripts.postinstall = "node ./node_modules/@axa-fr/react-oidc/bin/copy-service-worker-files.mjs public"' /tmp/gubbins-web/package.json > /tmp/gubbins-web/package.temp.json
+          mv /tmp/gubbins-web/package.temp.json /tmp/gubbins-web/package.json
+          # Update the next.config.js to prevent the standalone extension from searching a local version of diracx-web-components that does not exist
+          echo 'const nextConfig = { output: "export", images: { unoptimized: true }}; export default nextConfig;" > /tmp/gubbins-web/next.config.js
 
       - name: Install extensions dependencies
-        working-directory: /tmp/extensions
+        working-directory: /tmp/gubbins-web
         run: npm install
 
       - name: Upload the extensions directory
         uses: actions/upload-artifact@v4
         with:
-          name: gubbins
-          path: /tmp/extensions
+          name: gubbins-web
+          path: /tmp/gubbins-web
           retention-days: 1
   # ----------------------------------------------------------------------------#
   # In the following jobs, you should:                                          #
-  # - Replace /tmp/extensions with the path to your extension source code       #
+  # - Replace /tmp/gubbins-web with the path to your extension source code      #
   # - Remove the `needs: prepare-gubbins-as-a-standalone` line                  #
   # ============================================================================#
 
   # Build the extension image
   build-gubbins-dev-image:
     runs-on: ubuntu-latest
-    needs: prepare-gubbins-as-a-standalone
+    needs: prepare-gubbins-frontend-as-a-standalone
     if: ${{ github.event_name != 'push' || github.repository == 'DIRACGrid/diracx-web' }}
     steps:
       - uses: actions/checkout@v4
@@ -114,52 +171,72 @@ jobs:
       # ========================================================================#
       # WARNING: In your CI/CD pipeline, you should remove the following steps  #
       # ------------------------------------------------------------------------#
-      - name: Download the extensions directory
+      - name: Download gubbins-web
         uses: actions/download-artifact@v4
         with:
-          name: gubbins
-          path: /tmp/extensions
+          name: gubbins-web
+          path: /tmp/gubbins-web
       # ------------------------------------------------------------------------#
       # ========================================================================#
 
       # In your extension, you have to push the image to the registry (check deployment.yml)
       - name: Build Docker image (extension example)
         uses: docker/build-push-action@v6
         with:
-          context: /tmp/extensions
+          context: /tmp/gubbins-web
           push: false
           tags: ghcr.io/diracgrid/diracx-web/gubbins:dev
           platforms: linux/amd64,linux/arm64
 
-  # Run the demo with the extension source code
+  # Run the demo with the extension source code (frontend and backend)
   run-demo:
     runs-on: ubuntu-latest
-    needs: prepare-gubbins-as-a-standalone
+    needs: prepare-gubbins-frontend-as-a-standalone
     if: github.event_name != 'push' || github.repository == 'DIRACGrid/diracx-web'
     steps:
     - uses: actions/checkout@v4 
 
-    - name: Clone source 
+    - name: Clone source
       run: |
         cd ..
         git clone https://github.com/DIRACGrid/diracx-charts.git
 
     # ========================================================================#
     # WARNING: In your CI/CD pipeline, you should remove the following steps  #
     # ------------------------------------------------------------------------#
-    - name: Download the extensions directory
+    - name: Download gubbins
       uses: actions/download-artifact@v4
       with:
         name: gubbins
-        path: /tmp/extensions
+        path: /tmp/gubbins
+
+    - name: Clone diracx source 
+      run: |
+        cd ..
+        git clone https://github.com/DIRACGrid/diracx.git
+
+    - name: Download gubbins:services image
+      uses: actions/download-artifact@v4
+      with:
+        name: gubbins-services-img
+        path: /tmp/gubbins_services_image.tar
+
+    - name: Load docker image
+      run: docker load --input /tmp/gubbins_services_image.tar
+
+    - name: Download gubbins-web
+      uses: actions/download-artifact@v4
+      with:
+        name: gubbins-web
+        path: /tmp/gubbins-web
     # ------------------------------------------------------------------------#
     # ========================================================================#
 
     # Runs the demo with the extension source code
     - name: Start demo 
       run: |
         cd ..
-        diracx-charts/run_demo.sh --exit-when-done /tmp/extensions/
+        diracx-charts/run_demo.sh --exit-when-done --set-value developer.autoReload=false --ci-values ./diracx/extensions/gubbins_values.yaml --load-docker-image "gubbins/services:dev" diracx/ /tmp/gubbins/ /tmp/gubbins-web/
     
     - name: Debugging information
       run: |
@@ -194,4 +271,4 @@ jobs:
       with:
         browser: chrome
         config: baseUrl=${{ env.DIRACX_URL }}
-        project: /tmp/extensions
+        project: /tmp/gubbins-web
diff --git a/.prettierignore b/.prettierignore
@@ -1,9 +1,12 @@
-node_modules
+.github
 build
+CONTRIBUTING.md
 dist
-public
-.github
+docs
 jest.config.mjs
+node_modules
+public
+README.md
 
 packages/*/node_modules
 packages/*/build
@@ -19,4 +22,4 @@ packages/*/out
 
 **/release-please-config.json
 **/.release-please-manifest.json
-**/CHANGELOG.md
+**/CHANGELOG.md