feat(docs): add astro-graphql-plugin to the documentation (#1814)

* Add astro-graphql-plugin

* fix implementedBy links

* fix sidebar highlighting twice

* Update .prettierignore

* remove generated schema MDX

* remove generated graphql docs

* add generated docs content folder to .gitignore

* update astro plugin version to use the new build:start hook

* I don't really know what this does, but magic

* I learned to read comments, Max said to remove this step

* Update pnpm-lock.yaml

* Update index.mdx

.github/workflows/lint_test_build.yml

@@ -41,22 +41,6 @@ jobs:
         if: steps.verify-changed-files.outputs.files_changed == 'true'
         run: exit 1
 
-  documentation:
-    runs-on: ubuntu-22.04
-    needs: checkout
-    steps:
-      - uses: actions/checkout@v4
-      - uses: ./.github/workflows/rafiki/env-setup
-      - name: generate graphql api documentation
-        run: pnpm --filter documentation docs:graphql:generate && pnpm format
-      - name: verify changed files
-        uses: tj-actions/verify-changed-files@v16
-        id: verify-changed-files
-
-      - name: fail if docs were generated
-        if: steps.verify-changed-files.outputs.files_changed == 'true'
-        run: exit 1
-
   backend:
     runs-on: ubuntu-22.04
     needs: [checkout]

.prettierignore

@@ -15,4 +15,5 @@ build
 .docusaurus
 .cache-loader
 postman
-.postman
+.postman
+packages/documentation/src/content/docs/apis

packages/documentation/.gitignore

@@ -1,8 +1,13 @@
 # build output
 dist/
+
 # generated types
 .astro/
 
+# generated docs
+src/content/docs/apis/auth/*
+src/content/docs/apis/backend/*
+
 # dependencies
 node_modules/
 
@@ -12,7 +17,6 @@ yarn-debug.log*
 yarn-error.log*
 pnpm-debug.log*
 
-
 # environment variables
 .env
 .env.production

packages/documentation/astro.config.mjs

@@ -6,6 +6,7 @@ import react from '@astrojs/react'
 
 import remarkMath from 'remark-math'
 import rehypeMathjax from 'rehype-mathjax'
+import GraphQL from 'astro-graphql-plugin'
 
 // https://astro.build/config
 export default defineConfig({
@@ -153,28 +154,32 @@ export default defineConfig({
             {
               label: 'Backend Admin API',
               collapsed: true,
-              items: [
-                {
-                  label: 'Schema types',
-                  link: 'apis/backend/schema/'
-                }
-              ]
+              autogenerate: {
+                directory: 'apis/backend'
+              }
             },
             {
               label: 'Auth Admin API',
               collapsed: true,
-              items: [
-                {
-                  label: 'Schema types',
-                  link: 'apis/auth/schema/'
-                }
-              ]
+              autogenerate: {
+                directory: 'apis/auth'
+              }
             }
           ]
         }
       ]
     }),
-    react()
+    react(),
+    GraphQL({
+      schema: '../backend/src/graphql/schema.graphql',
+      output: './src/content/docs/apis/backend/',
+      linkPrefix: '/apis/backend/'
+    }),
+    GraphQL({
+      schema: '../auth/src/graphql/schema.graphql',
+      output: './src/content/docs/apis/auth/',
+      linkPrefix: '/apis/auth/'
+    })
   ],
   // Process images with sharp: https://docs.astro.build/en/guides/assets/#using-sharp
   image: {

packages/documentation/package.json

@@ -6,18 +6,16 @@
     "start": "astro dev",
     "build": "astro build",
     "preview": "astro preview",
-    "astro": "astro",
-    "docs:graphql:generate:backend": "./node_modules/.bin/graphql-markdown ../backend/src/graphql/schema.graphql > src/schema-dumps/backend_raw_schema.md",
-    "docs:graphql:generate:auth": "./node_modules/.bin/graphql-markdown ../auth/src/graphql/schema.graphql > src/schema-dumps/auth_raw_schema.md"
+    "astro": "astro"
   },
   "dependencies": {
     "@astrojs/react": "^2.3.2",
     "@astrojs/starlight": "^0.7.3",
     "@types/react": "^18.2.21",
     "@types/react-dom": "^18.2.7",
     "astro": "2.10.15",
+    "astro-graphql-plugin": "^0.0.7",
     "graphql": "^16.8.0",
-    "graphql-markdown": "^7.0.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "rehype-mathjax": "^4.0.3",