chore(docs): refactored wing libs into a list and new header items (#…

…1018) - Remove the folder in the Winglibs navigation for docs, now flat navigation (suggestion from @eladb ) - Added new header item for Libraries, also combined Playground and Examples into Explore (for UX issues). Co-authored-by: David Boyne <[email protected]>
winglang · Sep 23, 2024 · d887076 · d887076
1 parent 0c7df78
commit d887076
Show file tree

Hide file tree

Showing 34 changed files with 88 additions and 147 deletions.
diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -262,11 +262,10 @@ const config = {
           {
             to: "docs",
             position: "left",
-            label: "Install",
+            label: "Getting started",
             className: "header-text-link",
             target: "_self",
           },
-
           {
             to: "docs/learn",
             position: "left",
@@ -282,20 +281,30 @@ const config = {
             target: "_self",
           },
           {
-            // href: "https://github.com/winglang/examples",
-            to: "docs/examples",
+            to: "docs/winglibs/all-winglibs",
             position: "left",
-            label: "Examples",
+            label: "Libraries",
             className: "header-text-link",
+            target: "_self",
           },
           {
-            href: "https://www.winglang.io/play/",
-            position: "left",
-            label: "Playground",
-            className: "header-text-link",
-            target: "_self",
+            position: 'left',
+            label: 'Explore',
+            items: [
+              {
+                // href: "https://github.com/winglang/examples",
+                to: "docs/examples",
+                label: "Examples",
+                className: "header-text-link",
+              },
+              {
+                href: "https://www.winglang.io/play/",
+                label: "Playground",
+                className: "header-text-link",
+                target: "_self",
+              },
+            ]
           },
-
           {
             position: 'left',
             label: 'Community & Support',

diff --git a/scripts/winglibDocs.ts b/scripts/winglibDocs.ts
@@ -7,7 +7,9 @@ import { readFileSync, existsSync } from 'fs';
 
 const authorization = `token ${process.env.GITHUB_TOKEN}`;
 
-const WINGLIB_DIR = join(process.cwd(), 'versioned_docs', 'version-latest', '04-winglibs', '05-winglibs');
+const WINGLIB_DIR_TEMP_DIR = join(process.cwd(), 'versioned_docs', 'version-latest', '04-winglibs', '05-winglibs');
+const WINGLIB_DIR = join(WINGLIB_DIR_TEMP_DIR, '../');
+
 const categoryFile = `label: winglibs
 collapsible: true
 collapsed: true
@@ -106,16 +108,24 @@ const buildUrlsForPlatforms = (platforms: string[]) => {
   });
 
   // Write files to WINGLIB_DIR
-  await fs.rm(WINGLIB_DIR, { force: true, recursive: true });
-  await fs.mkdir(WINGLIB_DIR, { recursive: true });
+  await fs.rm(WINGLIB_DIR_TEMP_DIR, { force: true, recursive: true });
+  await fs.mkdir(WINGLIB_DIR_TEMP_DIR, { recursive: true });
+
+  // read all files in teh WINGLIB_DIR and find any that have winglib in the filename and remove it
+  const filesInDir = await fs.readdir(join(WINGLIB_DIR));
+  for (const file of filesInDir) {
+    if(file.includes('-winglib-')) {
+      await fs.rm(join(WINGLIB_DIR, file));
+    }
+  }
 
   // Write required docusuarus file for category
-  await fs.writeFile(join(WINGLIB_DIR, '_category_.yml'), categoryFile);
+  await fs.writeFile(join(WINGLIB_DIR_TEMP_DIR, '_category_.yml'), categoryFile);
 
   let table = `---
 title: List of winglibs
 id: all-winglibs
-sidebar_label: List of winglibs
+sidebar_label: Explore all Wing libraries
 description:  Table of all Wing libraries
 keywords: [winglib, Wing library]
 ---
@@ -127,7 +137,7 @@ keywords: [winglib, Wing library]
   // Create the table.
   // @ts-ignore
   for (const { title, version, description, platforms, demoURL, packageJson, winglib } of winglibs) {
-    table += `\n| [${title}](/docs/winglibs/winglibs/${winglib}) | [${packageJson.name}](/docs/winglibs/winglibs/${winglib}) |  v${version} | ${description} ${demoURL ? `([Example](${demoURL}))` : ''} | ${buildUrlsForPlatforms(platforms)} |`;
+    table += `\n| [${title}](/docs/winglibs/${winglib}) | [${packageJson.name}](/docs/winglibs/${winglib}) |  v${version} | ${description} ${demoURL ? `([Example](${demoURL}))` : ''} | ${buildUrlsForPlatforms(platforms)} |`;
   }
 
   // contributing to winglibs
@@ -137,7 +147,7 @@ keywords: [winglib, Wing library]
 
   `
 
-  await fs.writeFile(join(WINGLIB_DIR, '../04-toc.md'), table);
+  await fs.writeFile(join(WINGLIB_DIR_TEMP_DIR, '../04-toc.md'), table);
 
 
   for (const { winglib, readme, packageJson, title } of winglibs) {
@@ -153,24 +163,39 @@ keywords: [winglib, Wing library]
     }
 
     // remove any markdown images from the content (for now)
-    const contentWithoutImages = content.replace(/!\[.*\]\(.*\)/g, '');
-    console.log(join(WINGLIB_DIR, `${winglib}.md`))
+    let updatedContent = content.replace(/!\[.*\]\(.*\)/g, '');
+    console.log(join(WINGLIB_DIR_TEMP_DIR, `${winglib}.md`))
+
+    // Remove first header from README use docusuarus
+    updatedContent = updatedContent.replace(/^#\s.*$/m, '');
+    updatedContent = updatedContent.trim();
+
 
     const file = `---
 title: ${title}
 id: ${winglib}
-sidebar_label: ${title}
+sidebar_label: ${title} (winglib)
 description:  ${packageJson.wing?.docs?.summary || packageJson.description}
 keywords: [winglib, Wing library]
 ---
-${contentWithoutImages}
+${updatedContent}
 ---
 ${apiFileContent}
 `
 
-    await fs.writeFile(join(WINGLIB_DIR, `${winglib}.md`), file);
+    await fs.writeFile(join(WINGLIB_DIR_TEMP_DIR, `${winglib}.md`), file);
+  }
+
+  // Move all the winglibs into the correct directory
+  const filesInWingLib = await fs.readdir(join(WINGLIB_DIR));
+  let fileIndex = filesInWingLib.length;
+  for (const { winglib } of winglibs) {
+    fileIndex =  fileIndex + 1;
+    await fs.rename(join(WINGLIB_DIR_TEMP_DIR, `${winglib}.md`), join(WINGLIB_DIR, `${fileIndex}-winglib-${winglib}.md`));
   }
 
+  await fs.rm(WINGLIB_DIR_TEMP_DIR, { force: true, recursive: true });
+
   console.log("Cleaning up...");
   await fs.rm("winglibs.tgz");
   await fs.rm("winglibs", {

diff --git a/versioned_docs/version-latest/04-winglibs/04-toc.md b/versioned_docs/version-latest/04-winglibs/04-toc.md
@@ -1,7 +1,7 @@
 ---
 title: List of winglibs
 id: all-winglibs
-sidebar_label: List of winglibs
+sidebar_label: Explore all Wing libraries
 description:  Table of all Wing libraries
 keywords: [winglib, Wing library]
 ---

diff --git a/versioned_docs/version-latest/04-winglibs/05-winglibs/_category_.yml b/versioned_docs/version-latest/04-winglibs/05-winglibs/_category_.yml
diff --git a/...latest/04-winglibs/05-winglibs/cloudv2.md → ...-latest/04-winglibs/10-winglib-cloudv2.md b/...latest/04-winglibs/05-winglibs/cloudv2.md → ...-latest/04-winglibs/10-winglib-cloudv2.md
@@ -1,12 +1,10 @@
 ---
 title: cloudv2
 id: cloudv2
-sidebar_label: cloudv2
+sidebar_label: cloudv2 (winglib)
 description:  Standard cloud library for Wing
 keywords: [winglib, Wing library]
 ---
-# cloudv2
-
 This module contains a Wing-based implementation of the built-in `cloud` library. It's a work in progresss as part of a migration for our internal codebase.
 
 Here are the resources available so far:
@@ -33,7 +31,6 @@ let counter = new cloud.Counter();
 ## License
 
 This library is licensed under the [MIT License](./LICENSE).
-
 ---
 ## API Reference
 

diff --git a/...latest/04-winglibs/05-winglibs/cognito.md → ...-latest/04-winglibs/11-winglib-cognito.md b/...latest/04-winglibs/05-winglibs/cognito.md → ...-latest/04-winglibs/11-winglib-cognito.md
@@ -1,12 +1,10 @@
 ---
 title: Amazon Cognito
 id: cognito
-sidebar_label: Amazon Cognito
+sidebar_label: Amazon Cognito (winglib)
 description:  A wing library to work with Amazon Cognito
 keywords: [winglib, Wing library]
 ---
-# cognito
-
 A wing library to work with AWS Cognito.
 
 ## Prerequisites
@@ -86,6 +84,5 @@ curl -H "Authorization: ${TOKEN}" https://5b0y949eik.execute-api.us-east-1.amazo
 ## License
 
 This library is licensed under the [MIT License](./LICENSE).
-
 ---
 
diff --git a/...est/04-winglibs/05-winglibs/containers.md → ...test/04-winglibs/12-winglib-containers.md b/...est/04-winglibs/05-winglibs/containers.md → ...test/04-winglibs/12-winglib-containers.md
@@ -1,12 +1,10 @@
 ---
 title: Containers
 id: containers
-sidebar_label: Containers
+sidebar_label: Containers (winglib)
 description:  Deploy containers with Wing
 keywords: [winglib, Wing library]
 ---
-# Wing Containers Support
-
 This library allows deploying arbitrary containers with Wing.
 
 ## Installation

diff --git a/...atest/04-winglibs/05-winglibs/dynamodb.md → ...latest/04-winglibs/13-winglib-dynamodb.md b/...atest/04-winglibs/05-winglibs/dynamodb.md → ...latest/04-winglibs/13-winglib-dynamodb.md
@@ -1,12 +1,10 @@
 ---
 title: Amazon DynamoDB
 id: dynamodb
-sidebar_label: Amazon DynamoDB
+sidebar_label: Amazon DynamoDB (winglib)
 description:  A Wing library for Amazon DynamoDB
 keywords: [winglib, Wing library]
 ---
-# dynamodb
-
 ## Prerequisites
 
 - [winglang](https://winglang.io).
@@ -74,7 +72,6 @@ new DynamoDB(table.connection.clientConfig);
 ## License
 
 This library is licensed under the [MIT License](./LICENSE).
-
 ---
 ## API Reference
 

diff --git a/...st/04-winglibs/05-winglibs/eventbridge.md → ...est/04-winglibs/14-winglib-eventbridge.md b/...st/04-winglibs/05-winglibs/eventbridge.md → ...est/04-winglibs/14-winglib-eventbridge.md
@@ -1,12 +1,10 @@
 ---
 title: Amazon EventBridge
 id: eventbridge
-sidebar_label: Amazon EventBridge
+sidebar_label: Amazon EventBridge (winglib)
 description:  A Wing library for working with Amazon EventBridge
 keywords: [winglib, Wing library]
 ---
-# eventbridge
-
 A Wing library for working with [Amazon EventBridge](https://aws.amazon.com/eventbridge/).
 
 ## Prerequisites
@@ -60,7 +58,6 @@ wing compile -t @winglang/platform-awscdk -v eventBridgeName="my-bus" main.w
 ## License
 
 This library is licensed under the [MIT License](./LICENSE).
-
 ---
 ## API Reference
 

diff --git a/...test/04-winglibs/05-winglibs/fifoqueue.md → ...atest/04-winglibs/15-winglib-fifoqueue.md b/...test/04-winglibs/05-winglibs/fifoqueue.md → ...atest/04-winglibs/15-winglib-fifoqueue.md
@@ -1,12 +1,10 @@
 ---
 title: FIFO Queue
 id: fifoqueue
-sidebar_label: FIFO Queue
+sidebar_label: FIFO Queue (winglib)
 description:  A wing library to work with FIFO (first-in first-out) Queues
 keywords: [winglib, Wing library]
 ---
-# fifoqueue
-
 A wing library to work with FIFO (first-in first-out) Queues.
 
 To use the queue, set `groupId` to group messages and process them in an ordered fashion.
@@ -40,7 +38,6 @@ test "will push to queue" {
 ## License
 
 This library is licensed under the [MIT License](./LICENSE).
-
 ---
 ## API Reference
 

diff --git a/...-latest/04-winglibs/05-winglibs/github.md → ...n-latest/04-winglibs/16-winglib-github.md b/...-latest/04-winglibs/05-winglibs/github.md → ...n-latest/04-winglibs/16-winglib-github.md
@@ -1,12 +1,10 @@
 ---
 title: GitHub
 id: github
-sidebar_label: GitHub
+sidebar_label: GitHub (winglib)
 description:  A wing library to work with GitHub Probot
 keywords: [winglib, Wing library]
 ---
-# github
-
 A Wing library for working with [GitHub Probot](https://github.com/probot/probot)
 
 
@@ -140,7 +138,6 @@ let markdown = new github.ProbotApp(
 ## License
 
 This library is licensed under the [MIT License](./LICENSE).
-
 ---
 ## API Reference
 

diff --git a/...ion-latest/04-winglibs/05-winglibs/jwt.md → ...sion-latest/04-winglibs/17-winglib-jwt.md b/...ion-latest/04-winglibs/05-winglibs/jwt.md → ...sion-latest/04-winglibs/17-winglib-jwt.md
@@ -1,12 +1,10 @@
 ---
 title: JWT authentication
 id: jwt
-sidebar_label: JWT authentication
+sidebar_label: JWT authentication (winglib)
 description:  Wing library for JWT authentication
 keywords: [winglib, Wing library]
 ---
-# jwt
-
 A Wing library for working with JWT authentication.
 
 ## Prerequisites
@@ -35,7 +33,6 @@ test "will sign and verify" {
 ## License
 
 This library is licensed under the [MIT License](./LICENSE).
-
 ---
 ## API Reference
 

diff --git a/...ion-latest/04-winglibs/05-winglibs/k8s.md → ...sion-latest/04-winglibs/18-winglib-k8s.md b/...ion-latest/04-winglibs/05-winglibs/k8s.md → ...sion-latest/04-winglibs/18-winglib-k8s.md
@@ -1,12 +1,10 @@
 ---
 title: Kubernetes (k8s)
 id: k8s
-sidebar_label: Kubernetes (k8s)
+sidebar_label: Kubernetes (k8s) (winglib)
 description:  Wing for Kubernetes
 keywords: [winglib, Wing library]
 ---
-# Wing for Kubernetes
-
 A framework for synthesizing Kubernetes manifests using Winglang.
 
 ## Installation
@@ -133,7 +131,6 @@ deployment.exposeViaService(serviceType: k8s.ServiceType.LOAD_BALANCER);
 ## License
 
 This library is licensed under the [MIT License](./LICENSE).
-
 ---
 ## API Reference
 

diff --git a/...on-latest/04-winglibs/05-winglibs/lock.md → ...ion-latest/04-winglibs/19-winglib-lock.md b/...on-latest/04-winglibs/05-winglibs/lock.md → ...ion-latest/04-winglibs/19-winglib-lock.md
@@ -1,12 +1,10 @@
 ---
 title: Lock
 id: lock
-sidebar_label: Lock
+sidebar_label: Lock (winglib)
 description:  Wing library for cloud lock
 keywords: [winglib, Wing library]
 ---
-# lock
-
 ## Prerequisites
 
 * [winglang](https://winglang.io).
@@ -82,7 +80,6 @@ test "count with expiry" {
 ## License
 
 This library is licensed under the [MIT License](./LICENSE).
-
 ---
 ## API Reference