docs: prototype partials DOC-1159

.gitignore

@@ -61,4 +61,7 @@ screenshots/
 tests/screenshot.spec.ts-snapshots/
 test-results/
 playwright-report/
-artifact.zip
+artifact.zip
+
+# Ignore _partials/index.ts
+_partials/index.ts

Makefile

@@ -58,6 +58,7 @@ init: ## Initialize npm dependencies
 	npx husky install
 
 start: ## Start a local development server
+	make generate-partials
 	npm run start
 
 build: ## Run npm build
@@ -203,6 +204,11 @@ format-images: ## Format images
 	@echo "formatting images in /static/assets/docs/images/ folder"
 	./scripts/compress-convert-images.sh
 
+###@ Generate _partials/index.ts required to automatic partials usage.
+
+generate-partials: ## Generate
+	./scripts/generate-partials.sh
+
 ###@ Aloglia Indexing
 
 update-dev-index: ## Update the Algolia index for the dev environment

_partials/clusters/_cluster-profile.mdx

@@ -0,0 +1,6 @@
+---
+partial_category: clusters
+partial_name: cluster-profile
+---
+
+This is the second import {props.cloud} {props.version}. 

_partials/getting-started/_palette-setup.mdx

@@ -0,0 +1,8 @@
+{/* ---
+partial_category: getting-started
+partial_name: palette-setup
+--- */}
+
+This is how we set up Palette with {props.cloud} {props.version}. 
+
+[Test](/getting-started/additional-capabilities)

docs/docs-content/_partials/_getting-started_aws_palette-setup.mdx

@@ -0,0 +1 @@
+This is how we set up Palette with {props.cloud} {props.version}. 

docs/docs-content/getting-started/getting-started.md

@@ -8,6 +8,54 @@ sidebar_custom_props:
 tags: ["getting-started"]
 ---
 
+### Partials test
+
+#### Approach 1
+
+<!-- import Setup from '../_partials/_getting-started_aws_palette-setup.mdx';
+
+<Setup cloud="AWS" version="2.0"/> -->
+
+#### Approach 2
+
+<!-- import Setup2 from '../../../_partials/getting-started/_palette-setup.mdx';
+
+<Setup2 cloud="AWS" version="2.0"/> -->
+
+#### Approach 3
+
+<!-- <PartialsComponent
+  category="GETTING-STARTED"
+  name="PaletteSetup" 
+  props={[
+    {
+      key:"cloud",
+      value:"AWS",
+    },
+    {
+      key:"version",
+      value:"2.0",
+    }
+  ]} 
+/> -->
+
+#### Approach 4
+
+<!-- <PartialsComponentFrontMatter
+  category="clusters"
+  name="cluster-profile" 
+  props={[
+    {
+      key:"cloud",
+      value:"AWS",
+    },
+    {
+      key:"version",
+      value:"2.0",
+    }
+  ]} 
+/> -->
+
 This page gives you an overview of how to get started with Spectro Cloud Palette and begin leveraging its Kubernetes
 full-stack management at scale. Palette's unique capabilities provide end-to-end declarative cluster management, cluster
 monitoring and reconciliation, as well as enterprise-grade security.
@@ -33,7 +81,7 @@ The first step towards adopting Palette in your organization is to
 We have curated the pages in the Getting Started section to give you a gradual introduction to the fundamental concepts
 and workflows you need to deploy and manage Kubernetes clusters through Palette.
 
-<div class="desktop-only-display">
+<div className="desktop-only-display">
 
 ![Overview of the getting started journey rocket](/getting-started/getting-started_getting-started_journey-overview.webp)
 

package.json

@@ -5,7 +5,7 @@
   "scripts": {
     "docusaurus": "docusaurus",
     "start": "docusaurus start --host 0.0.0.0 --port 9000",
-    "build": "npm run generate-api-docs && docusaurus build",
+    "build": "npm run generate-api-docs && npm run generate-partials && docusaurus build",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy",
     "clear": "docusaurus clear",
@@ -18,6 +18,7 @@
     "generate-api-docs": "npm run run-api-parser && docusaurus gen-api-docs palette && docusaurus gen-api-docs emc",
     "clean-api-docs": "docusaurus clean-api-docs palette && docusaurus clean-api-docs emc",
     "run-api-parser": "node utils/api-parser/index.js",
+    "generate-partials": "./scripts/generate-partials.sh",
     "lint": "eslint . --ext .js,.ts,.jsx,.tsx",
     "lint:fix": "npm run lint -- --fix",
     "format": "prettier --write \"**/*.{js,jsx,json,ts,tsx,md,mdx,css}\"",

scripts/generate-partials.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+
+# Enable error handling
+set -e
+
+echo "Starting generation of _partials/index.ts."
+
+# # Remove the index.ts file if it exists already.
+rm -f _partials/index.ts
+
+# Create the file and add the generated warning.
+echo "// This file is generated. DO NOT EDIT!" >> _partials/index.ts
+
+# Find all the MDX files recursively in the _partials folder.
+# Loop through each file.
+find _partials -name "*.mdx" -print0 | while read -d $'\0' path
+do
+    module_name=$(basename ${path} .mdx | tr -d '_' | tr -d '-')
+    echo "export * as ${module_name}${RANDOM} from '@site/${path}';" >> _partials/index.ts
+done
+
+echo "Completed generation of _partials/index.ts."

src/components/PartialsComponent/PartialsCategories.tsx

@@ -0,0 +1,26 @@
+import { ClusterPartials } from "./maps/ClustersPartials"
+import { GettingStartedPartials } from "./maps/GettingStartedPartials"
+import { PartialsMap } from "./maps/PartialsMap"
+
+export interface PartialsCategory {
+    category: string; 
+    map: PartialsMap;
+}
+
+interface PartialsMapCategories {
+    maps: PartialsCategory[]
+}
+
+// Maintain a map of existing partials 
+export const AllPartials: PartialsMapCategories = {
+   maps: [
+        {
+            category: "GETTING-STARTED",
+            map: GettingStartedPartials
+        },
+        {
+            category: "CLUSTERS",
+            map: ClusterPartials
+        }
+    ]
+}; 

src/components/PartialsComponent/PartialsComponent.tsx

@@ -0,0 +1,50 @@
+import React from "react";
+import { AllPartials, PartialsCategory } from "./PartialsCategories"
+
+interface InputProperty {
+    key: string,
+    value: string,
+}
+
+interface PartialsComponentDetails {
+    category: string;
+    name: string;
+    // Pass the key-value property pairs 
+    props: InputProperty[];
+}
+
+export default function PartialsComponent(details : PartialsComponentDetails) : React.ReactElement {
+
+    var foundCategoryMap = null;
+    AllPartials.maps.forEach((val) => {
+        if (val.category == details.category) {
+            foundCategoryMap = val;
+            return
+        }
+    })
+
+    if (!foundCategoryMap) {
+        throw new Error("No partial found for category".
+            concat(details.name).
+            concat("."));
+    }
+
+    const partialsMap = foundCategoryMap as PartialsCategory;
+    if (!partialsMap.map[details.name]) {
+        throw new Error("No partial found for name ".
+            concat(details.name).
+            concat("in category ").
+            concat(details.category).
+            concat(".="));
+    }
+
+    // Map elements to index signatures
+    var propAttribute: {[key: string] : string} = {}
+    details.props.map((val) => {
+        propAttribute[val.key] = val.value
+    })    
+
+    var cloned = React.cloneElement(partialsMap.map[details.name], propAttribute)
+    return cloned;
+}
+

src/components/PartialsComponent/index.ts

@@ -0,0 +1,3 @@
+import PartialsComponent from "./PartialsComponent";
+
+export default PartialsComponent;

src/components/PartialsComponent/maps/ClustersPartials.tsx

@@ -0,0 +1,9 @@
+import React from "react";
+// Import each partial here 
+import ClusterProfiles from "@site/_partials/clusters/_cluster-profile.mdx"
+import { PartialsMap } from "./PartialsMap"
+
+// Maintain a map of existing partials 
+export const ClusterPartials: PartialsMap = {
+    "ClusterProfile": <ClusterProfiles />,
+};

src/components/PartialsComponent/maps/GettingStartedPartials.tsx

@@ -0,0 +1,9 @@
+import React from "react";
+// Import each partial here 
+import PaletteSetup from "@site/_partials/getting-started/_palette-setup.mdx"
+import { PartialsMap } from "./PartialsMap"
+
+// Maintain a map of existing partials 
+export const GettingStartedPartials: PartialsMap = {
+    "PaletteSetup": <PaletteSetup />,
+};

src/components/PartialsComponent/maps/PartialsMap.tsx

@@ -0,0 +1,8 @@
+import React from "react";
+
+export interface PartialsMap {
+    [key: string]: React.ReactElement;
+}
+
+// {key: x, value: y}
+// {x : y}

src/components/PartialsComponentFrontMatter/PartialsComponent.tsx

@@ -0,0 +1,78 @@
+import React, { FunctionComponent } from "react";
+// Import all the partials as one module. 
+import * as PartialModules from "@site/_partials";
+
+export interface PartialsMap {
+    [key: string]: FunctionComponent;
+}
+
+interface InputProperty {
+    key: string,
+    value: string,
+}
+
+interface PartialsComponentDetails {
+    category: string;
+    name: string;
+    // Pass the key-value property pairs 
+    props: InputProperty[];
+}
+
+// !!!!! DISABLED ONLY FOR TEAM DEMO !!!!
+// const AllPartials = importPartials()
+const AllPartials = {}
+
+export default function PartialsComponentFrontMatter(details : PartialsComponentDetails) : React.ReactElement {
+    var mapKey = getMapKey(details.category, details.name)
+
+    if (!AllPartials[mapKey]) {
+    throw new Error("No partial found for name ".
+        concat(details.name).
+        concat(" in category ").
+        concat(details.category).
+        concat(".="));
+    }
+
+    // Map elements to index signatures
+    var propAttribute: {[key: string] : string} = {}
+    details.props.map((val) => {
+        propAttribute[val.key] = val.value
+    })
+
+    return React.createElement(AllPartials[mapKey], propAttribute);
+}
+
+function importPartials() : PartialsMap {
+    const pmap : PartialsMap = {}
+
+    // The keys are the names of each exported module in _partials/index.ts
+    const partialKeys = Object.keys(PartialModules);
+
+    for (const pkey of partialKeys) {
+        var currentPartial = PartialModules[pkey];
+        var catFrontMatter = currentPartial["frontMatter"]["partial_category"];
+        var nameFrontMatter = currentPartial["frontMatter"]["partial_name"];
+
+        if (!catFrontMatter || !nameFrontMatter) {
+            throw new Error("Please specify partial_category and partial_name for ".
+            concat(pkey).
+            concat("."));
+        }
+
+        var mapKey = getMapKey(catFrontMatter, nameFrontMatter)
+        if (pmap[mapKey]) {
+            throw new Error("Duplicate partial defined for name ".
+                concat(nameFrontMatter).
+                concat(" in category ").
+                concat(catFrontMatter).
+                concat("."));
+        }
+
+        pmap[mapKey] = currentPartial.default as FunctionComponent;
+    }
+    return pmap
+}
+
+function getMapKey(category: string, name: string): string {
+   return category.concat('#').concat(name)
+}

src/components/PartialsComponentFrontMatter/index.ts

@@ -0,0 +1,3 @@
+import PartialsComponentFrontMatter from "./PartialsComponent";
+
+export default PartialsComponentFrontMatter;

src/theme/MDXComponents/MDXComponents.ts

@@ -12,6 +12,8 @@ import TOCInline from "@theme/TOCInline";
 import { TechnicalPreviewReleaseNote as TpBadge } from "@site/src/components/Badges";
 import SimpleCardGrid from "@site/src/components/SimpleCardGrid/index";
 import ReleaseNotesVersions from "@site/src/components/ReleaseNotesVersions/index";
+import PartialsComponent from "@site/src/components/PartialsComponent";
+import PartialsComponentFrontMatter from "@site/src/components/PartialsComponentFrontMatter";
 
 export default {
   ...MDXComponents,
@@ -28,4 +30,6 @@ export default {
   TpBadge,
   SimpleCardGrid,
   ReleaseNotesVersions,
+  PartialsComponent,
+  PartialsComponentFrontMatter: PartialsComponentFrontMatter,
 };

tsconfig.json

@@ -1,10 +1,10 @@
 {
   // This file is not used in compilation. It is here just for a nice editor experience.
   "extends": "@tsconfig/docusaurus/tsconfig.json",
-  "include": ["src", "declarations.d.ts", "utils"],
+  "include": ["src", "declarations.d.ts", "utils", "**/*.mdx",],
   "exclude": ["src/deprecated"],
   "compilerOptions": {
-    "types": ["node", "jest", "@testing-library/jest-dom"],
+    "types": ["node", "jest", "@testing-library/jest-dom", "mdx"],
     "esModuleInterop": true,
     "target": "es6",
     "module": "Node16",