dev: developer docs (#1011)

* feat: add docusaurus docs * feat: add nextra docs * chore: update pnpm files * chore: add autoprefixer to catalog * fix: improve * fix: add built in serve for nextra export * chore: remove docusaurus * chore: do slightly clearner install of pnpm lock * chore: do slightly clearner install of pnpm lock * chore: move over some other readmes * chore: update layout slightly * chore: disable eslint for builds * feat: setup gh-actions deploy * fix: deploy under subpath * fix: add pr number on preview builds * fix: better ignore for doc build * fix: actually install deps * fix: better filter * chore: meaningless docs change * chore: better filter * fix: try more permissions * fix: even more permissions * fix: even broader permissions and give up on turbo for now * fix: add fetch depth 0 * fix: add utility to get correct path * fix: better path * fix: replace url comments with actual code * fix: test if normal deploy works * fix: better conditions * fix better permissions * fix: on merge main * fix: also run thing on close * fix: add needs * fix: use correct action keyword * fix: checkout first * fix: add back reopened label * fix: correct link for main * fix: smaller permissions
pubpub · Mar 7, 2025 · e5f2d4c · e5f2d4c
1 parent 33e510b
commit e5f2d4c
Show file tree

Hide file tree

Showing 39 changed files with 4,131 additions and 138 deletions.
diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml
@@ -0,0 +1,80 @@
+name: Build Docs
+
+on:
+    workflow_call:
+        inputs:
+            preview:
+                type: boolean
+                required: true
+
+jobs:
+    build-docs:
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout
+              with:
+                  # necessary in order to show latest updates in docs
+                  fetch-depth: 0
+              uses: actions/checkout@v4
+
+            - name: Install Node.js
+              uses: actions/setup-node@v4
+              with:
+                  node-version: 22.13.1
+
+            - uses: pnpm/action-setup@v4
+              name: Install pnpm
+              with:
+                  run_install: false
+
+            - name: Get pnpm store directory
+              id: get-store-path
+              shell: bash
+              run: |
+                  echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_OUTPUT
+
+            - name: Setup pnpm cache
+              uses: actions/cache@v4
+              with:
+                  path: ${{ steps.get-store-path.outputs.STORE_PATH }}
+                  key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+                  restore-keys: |
+                      ${{ runner.os }}-pnpm-store-
+
+            # - name: Cache turbo
+            #   uses: actions/cache@v4
+            #   with:
+            #       path: .turbo
+            #       key: ${{ runner.os }}-turbo-${{ github.sha }}
+            #       restore-keys: |
+            #           ${{ runner.os }}-turbo-
+
+            - name: Install dependencies
+              run: pnpm install --frozen-lockfile --prefer-offline
+
+            - name: set pr number if preview
+              id: set-pr-number
+              if: inputs.preview == true
+              run: |
+                  echo "PR_NUMBER=${{ github.event.pull_request.number }}" >> $GITHUB_OUTPUT
+
+            - name: Build docs
+              env:
+                  PR_NUMBER: ${{ steps.set-pr-number.outputs.PR_NUMBER }}
+              run: pnpm --filter docs build
+
+            - name: Deploy docs main 🚀
+              if: inputs.preview == false
+              uses: JamesIves/github-pages-deploy-action@v4
+              with:
+                  folder: docs/out
+                  branch: gh-pages
+                  clean-exclude: pr-preview
+                  force: false
+
+            - name: Deploy docs preview
+              if: inputs.preview == true
+              uses: rossjrw/pr-preview-action@v1
+              with:
+                  source-dir: docs/out
+                  action: deploy
diff --git a/.github/workflows/on_main.yml b/.github/workflows/on_main.yml
@@ -40,3 +40,12 @@ jobs:
         secrets:
             AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
             AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+
+    deploy-docs:
+        permissions:
+            contents: write
+            pages: write
+            pull-requests: write
+        uses: ./.github/workflows/build-docs.yml
+        with:
+            preview: false
diff --git a/.github/workflows/on_pr.yml b/.github/workflows/on_pr.yml
@@ -14,16 +14,33 @@ permissions:
     contents: read
 
 jobs:
+    path-filter:
+        runs-on: ubuntu-latest
+        if: github.event.action == 'opened' || github.event.action == 'reopened' || github.event.action == 'synchronize' || github.event.action == 'closed'
+        outputs:
+            docs: ${{ steps.changes.outputs.docs }}
+        steps:
+            - uses: actions/checkout@v4
+            - uses: dorny/paths-filter@v2
+              id: changes
+              with:
+                  filters: |
+                      docs:
+                          - 'docs/**'
+
     ci:
+        if: github.event.action == 'opened' || github.event.action == 'reopened' || github.event.action == 'synchronize'
         uses: ./.github/workflows/ci.yml
 
     build-all:
+        if: github.event.action == 'opened' || github.event.action == 'reopened' || github.event.action == 'synchronize'
         uses: ./.github/workflows/ecrbuild-all.yml
         secrets:
             AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
             AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
 
     e2e:
+        if: github.event.action == 'opened' || github.event.action == 'reopened' || github.event.action == 'synchronize'
         needs:
             - build-all
             # could theoretically be skipped, but in practice is always faster
@@ -85,3 +102,33 @@ jobs:
                   AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
                   AWS_REGION: ${{ env.AWS_REGION }}
                   PULLPREVIEW_LOGGER_LEVEL: DEBUG
+
+    deploy-docs-preview:
+        permissions:
+            contents: write
+            pages: write
+            pull-requests: write
+        needs:
+            - path-filter
+        if: (github.event.action == 'opened' || github.event.action == 'reopened' || github.event.action == 'synchronize') && needs.path-filter.outputs.docs == 'true'
+        uses: ./.github/workflows/build-docs.yml
+        with:
+            preview: true
+
+    close-docs-preview:
+        needs:
+            - path-filter
+        permissions:
+            contents: write
+            pages: write
+            pull-requests: write
+        if: github.event.action == 'closed' && needs.path-filter.outputs.docs == 'true'
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+
+            - name: Close docs preview
+              uses: rossjrw/pr-preview-action@v1
+              with:
+                  source-dir: docs/out
+                  action: remove
diff --git a/core/package.json b/core/package.json
@@ -171,7 +171,7 @@
 		"@types/unist": "^3.0.2",
 		"@types/uuid": "^9.0.2",
 		"@vitejs/plugin-react": "^4.2.1",
-		"autoprefixer": "^10.4.14",
+		"autoprefixer": "catalog:",
 		"csv-parse": "^5.5.2",
 		"dotenv": "^16.4.5",
 		"dotenv-cli": "^7.2.1",

diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,43 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+_pagefind/
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,5 @@
+# PubPub Development Documentation
+
+This is the development documentation for PubPub, mostly intended for internal use.
+
+For documentation on how to use PubPub, see <https://help.knowledgefutures.org>.
diff --git a/docs/content/_meta.ts b/docs/content/_meta.ts
@@ -0,0 +1,7 @@
+import type { MetaRecord} from 'nextra'
+
+const meta: MetaRecord = {
+	infrastructure: "🏗️ Infrastructure",
+};
+
+export default meta;
diff --git a/packages/db/README.md → docs/content/development/db.mdx b/packages/db/README.md → docs/content/development/db.mdx
@@ -32,17 +32,17 @@ pnpm --filter db migrate-dev
 
 If you have added a new table, make sure to add
 
-```ts
+```ts filename="/packages/db/src/public.ts"
 export * from "./tableName";
 ```
 
-to `src/public.ts`, otherwise you will not be able to import it.
+to `/packages/db/src/public.ts`, otherwise you will not be able to import it.
 
 ## Special hooks
 
 Because `kanel` is a bit messy, we have a few special hooks to make it easier to work with.
 
-See `src/kanel` for more details.
+See `packages/db/src/kanel` for more details.
 
 ## Adding extra types you want to use