ci: enhance docs publishing workflow (#1139)

.github/workflows/publish-docs.yaml

@@ -1,49 +1,77 @@
 name: Deploy to GitHub Pages
 
 on:
+  workflow_dispatch:
   push:
-    branches:
-      - main
+    paths:
+      - 'docs/**'
+      - '.github/workflows/publish-docs.yaml'
 
 permissions:
   contents: read
   pages: write
   id-token: write
+  pull-requests: write
 
+# Allow only one concurrent deployment
 concurrency:
   group: "pages"
-  cancel-in-progress: false
+  cancel-in-progress: true
 
 jobs:
-  # Single deploy job since we're just deploying
-  deploy:
+  build-and-deploy:
+    runs-on: ubuntu-latest
     environment:
-      name: github-pages
+      name: ${{ github.ref == 'refs/heads/main' && 'github-pages' || 'preview' }}
       url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
     steps:
-      - name: Checkout
-        uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+
       - uses: actions/setup-node@v3
         with:
           node-version: 18
-          cache: yarn
-          cache-dependency-path: 'docs/package-lock.json'
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
 
-      - name: Install dependencies
+      - name: Build docs
         working-directory: docs
-        run: yarn install --frozen-lockfile
-      - name: Build website
-        working-directory: docs
-        run: yarn build
+        run: |
+          npm ci
+          npm run build
 
       - name: Setup Pages
-        uses: actions/configure-pages@v3
-      - name: Upload artifact
+        uses: actions/configure-pages@v4
+
+      - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          # Upload entire repository
-          path: 'docs/build'
-      - name: Deploy to GitHub Pages
+          path: docs/build
+          name: github-pages
+
+      - name: Deploy
         id: deployment
-        uses: actions/deploy-pages@v2
+        if: |
+          github.ref == 'refs/heads/main' ||
+          github.ref == 'refs/heads/docs-test' ||
+          startsWith(github.ref, 'refs/heads/docs/')
+        uses: actions/deploy-pages@v4
+        with:
+          artifact_name: github-pages
+          preview: ${{ github.ref != 'refs/heads/main' }}
+
+      - name: Comment PR
+        if: |
+          github.event_name == 'pull_request' &&
+          (github.ref == 'refs/heads/docs-test' ||
+           startsWith(github.ref, 'refs/heads/docs/'))
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const url = '${{ steps.deployment.outputs.page_url }}';
+            const message = `📚 Documentation preview available at: ${url}`;
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: message
+            });

docs/README.md

@@ -1,25 +1,25 @@
-# Website
+# Docs site
 
-This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+The documentation for this project is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
 
 ### Installation
 
 ```
-$ yarn
+$ npm i
 ```
 
 ### Local Development
 
 ```
-$ yarn start
+$ npm run start
 ```
 
 This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
 
 ### Build
 
 ```
-$ yarn build
+$ npm run build
 ```
 
 This command generates static content into the `build` directory and can be served using any static contents hosting service.
@@ -29,13 +29,13 @@ This command generates static content into the `build` directory and can be serv
 Using SSH:
 
 ```
-$ USE_SSH=true yarn deploy
+$ USE_SSH=true npm run deploy
 ```
 
 Not using SSH:
 
 ```
-$ GIT_USER=<Your GitHub username> yarn deploy
+$ GIT_USER=<Your GitHub username> npm run deploy
 ```
 
 If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
@@ -45,5 +45,6 @@ If you are using GitHub pages for hosting, this command is a convenient way to b
 Some common defaults for linting/formatting have been set for you. If you integrate your project with an open source Continuous Integration system (e.g. Travis CI, CircleCI), you may check for issues using the following command.
 
 ```
-$ yarn ci
+$ npm run ci
 ```
+

docs/docs/modules/agents/executor/index.mdx

@@ -5,6 +5,7 @@ sidebar_position: 2
 
 import CodeBlock from "@theme/CodeBlock";
 import Example from "@examples/mrkl-agent-example/mrkl_agent.go";
+import DocCardList from "@theme/DocCardList";
 
 # Agent Executors
 
@@ -18,5 +19,4 @@ To make agents more powerful we need to make them iterative, ie. call the model
 An example that initialize a MRKL (Modular Reasoning, Knowledge and Language, pronounced "miracle") agent executor.
 <CodeBlock language="go">{Example}</CodeBlock>
 
-import DocCardList from "@theme/DocCardList";
 <DocCardList />

docs/docusaurus.config.js

@@ -5,6 +5,8 @@
 // eslint-disable-next-line import/no-extraneous-dependencies
 const { ProvidePlugin } = require("webpack");
 const path = require("path");
+const lightCodeTheme = require('prism-react-renderer').themes.github;
+const darkCodeTheme = require('prism-react-renderer').themes.dracula;
 
 const examplesPath = path.resolve(__dirname, "..", "examples");
 
@@ -124,8 +126,8 @@ const config = {
     /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
     ({
       prism: {
-        theme: require("prism-react-renderer/themes/vsLight"),
-        darkTheme: require("prism-react-renderer/themes/vsDark"),
+        theme: lightCodeTheme,
+        darkTheme: darkCodeTheme,
       },
       image: "img/parrot-chainlink-icon.png",
       navbar: {