feat/126: documentation site builder - rspress

.ls-lint.yml

@@ -30,3 +30,4 @@ ignore:
   - '**/dist'
   - '**/documentation'
   - '**/node_modules'
+  - 'apps/docs/src/public'

apps/docs/.gitignore

@@ -0,0 +1,16 @@
+# Local
+.DS_Store
+*.local
+*.log*
+
+# Dist
+node_modules
+dist/
+
+# generated files
+src/public/
+
+# IDE
+.vscode/*
+!.vscode/extensions.json
+.idea

apps/docs/README.md

@@ -0,0 +1,67 @@
+# Rspress Website
+
+This documentation site project works within the Accelint Standard Toolkit (DevTK) and within that repo as a package in a monorepo.
+
+To only run commands in this module/package of the monorepo prefix commands with:
+
+```bash
+# from the root of the repo
+pnpm --filter @accelint/docs # ...
+```
+
+## Setup
+
+Install the dependencies:
+
+```bash
+pnpm install
+# or
+pnpm --filter @accelint/docs install
+```
+
+## Get Started
+
+Start the dev server:
+
+```bash
+pnpm --filter @accelint/docs dev
+# or
+pnpm --filter @accelint/docs run dev
+```
+
+Build the website for production:
+
+```bash
+pnpm --filter @accelint/docs build
+# or
+pnpm --filter @accelint/docs run build
+```
+
+Preview the production build locally:
+
+```bash
+pnpm --filter @accelint/docs preview
+# or
+pnpm --filter @accelint/docs run preview
+```
+
+## Interactive and "Rendered" Code Blocks
+
+The RSPress plugin for "[playground](https://rspress.dev/plugin/official-plugins/playground)"s, or interactive code examples, is enabled by declaring a code block with <code>\`\`\`jsx playground</code> in `.mdx` documents; NOTE the file extension must be `.mdx`. Additionally the code block must export a React component.
+
+```jsx playground
+// ```jsx playground <--- declare code block with this line
+export default const fun = () => <div>Fun!</div>
+```
+
+## API (docblock) Documentation
+
+Documentation from the in-code docblocks are easily integrated into each page with the following snippet:
+
+```mdx
+import Typedoc from "../../typedocs/functions/<name-of-function>.md";
+
+<Typedoc />
+```
+
+The relative path-ing - "../../" - will be dependent on the relative path-ing of each module.

apps/docs/biome.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.8.0/schema.json",
+  "organizeImports": {
+    "enabled": true
+  },
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "formatter": {
+    "indentStyle": "space"
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single"
+    }
+  },
+  "css": {
+    "parser": {
+      "cssModules": true
+    }
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    }
+  }
+}

apps/docs/lib/audit-modules.mjs

@@ -0,0 +1,61 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { getPaths } from './get-paths.mjs';
+
+/**
+ * This file is meant to be a CLI utility for auditing the content in the documentation
+ * site reporting on the existence of the bare minimum of pages. Optionally - using the
+ * CLI argument `--stubMissing` - the missing pages could be created in a batch rather
+ * than requiring manual work.
+ *
+ * @example
+ * node ./apps/docs/lib/audit-modules.mjs
+ * // will list missing documentation pages if any are/aren't found to be where expected
+ * // will print "All expected files exist." if all expected documentation pages exist
+ *
+ * @example
+ * node ./apps/docs/lib/audit-modules.mjs --stubMissing
+ * // will create "stub" files for missing documentation pages; ready for editing
+ */
+
+const addMissingDocuments = process.argv.includes('--stubMissing');
+const pagesLocation = path.join(
+  process.cwd(),
+  'apps',
+  'docs',
+  'src',
+  'packages',
+);
+const pages = getPaths(
+  path.join(process.cwd(), 'packages'),
+  undefined,
+  1,
+).flat();
+
+let cleanAudit = true;
+
+for (const page of pages) {
+  const name = path.join(pagesLocation, page);
+  const md = `${name}.md`;
+  const mdx = `${name}.mdx`;
+
+  const exists = () => fs.existsSync(md) || fs.existsSync(mdx);
+
+  if (!exists() && addMissingDocuments) {
+    // Ensure the directory exists before writing the file
+    fs.mkdirSync(path.dirname(md), { recursive: true });
+
+    // Write the initial file content
+    fs.writeFileSync(md, `# ${page}\n`, 'utf8');
+  }
+
+  if (!exists()) {
+    cleanAudit = false;
+    console.log(`Missing page: .${md.replace(process.cwd(), '')}(x)`);
+  }
+}
+
+if (cleanAudit) {
+  console.log('All expected files exist.');
+}

apps/docs/lib/get-paths.mjs

@@ -0,0 +1,37 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const PATTERN_EXCLUDE =
+  /__fixtures__|coverage|dist|documentation|ladle|node_modules|styles|test|types|\.(?:bench|config|css|d|ladle|stories|test|turbo)/;
+
+/**
+ * Recursively gather the filesystem directories (folders) into an array of strings
+ * filtering out specific entries as they aren't necessary for the intended use case.
+ *
+ * @param dir the starting point to read from
+ * @param root the top-most level of the recursion; used to trim full path
+ * @param depth how deep of a structure to return back
+ * @returns a string array of directories
+ */
+export const getPaths = (dir, root = dir, depth = 3) =>
+  Array.from(getPathsGen(dir, root, depth));
+
+function* getPathsGen(dir, root, depth) {
+  for (const fileName of fs.readdirSync(dir)) {
+    const filePath = path.resolve(dir, fileName);
+
+    if (
+      fs.statSync(filePath).isDirectory() &&
+      !PATTERN_EXCLUDE.test(filePath)
+    ) {
+      const current = filePath.replace(root, '').replace('/src', '');
+      const next = () => getPaths(filePath, root, depth - 1);
+
+      yield* filePath.endsWith('src')
+        ? next()
+        : depth < 1
+          ? [current]
+          : [current, next()].filter((item) => item.length);
+    }
+  }
+}

apps/docs/lib/install.tsx

@@ -0,0 +1,52 @@
+// biome-ignore lint/correctness/noUnusedImports: <explanation>
+import React from 'react';
+import { Tab, Tabs } from 'rspress/theme';
+
+export default function Component({ pack }: { pack: string }) {
+  return (
+    <Tabs>
+      {...[
+        tab('pnpm', 'add', pack),
+        tab('npm', 'install -save', pack),
+        tab('yarn', 'add', pack),
+      ]}
+    </Tabs>
+  );
+}
+
+function tab(label: string, command: string, pack: string) {
+  return (
+    <Tab label={label}>
+      <div aria-label={label} className='rounded px-2'>
+        <div className='language-bash'>
+          <div className='rspress-code-content rspress-scrollbar'>
+            <div>
+              <pre className='code' style={{ backgroundColor: 'inherit' }}>
+                <code className='language-bash' style={{ whiteSpace: 'pre' }}>
+                  <span style={{ display: 'block', padding: '0px 1.25rem' }}>
+                    <span
+                      className='linenumber react-syntax-highlighter-line-number'
+                      style={{
+                        display: 'inline-block',
+                        minWidth: '1.25em',
+                        paddingRight: '1em',
+                        textAlign: 'right',
+                        userSelect: 'none',
+                        color: 'var(--code-token-comment)',
+                      }}
+                    >
+                      1
+                    </span>
+                    <span>
+                      {label} {command} {`@accelint/${pack}`}
+                    </span>
+                  </span>
+                </code>
+              </pre>
+            </div>
+          </div>
+        </div>
+      </div>
+    </Tab>
+  );
+}

apps/docs/lib/plugin-remark-custom-install.ts

@@ -0,0 +1,44 @@
+// NOTE: this is not being used but is an example of how to build a custom markdown plugin
+
+type NodeMeta = {
+  children?: any[];
+  lang: string;
+  // position: {
+  //   end: NodeMetaPosition;
+  //   start: NodeMetaPosition;
+  // };
+  type: string;
+};
+
+// type NodeMetaPosition = object;
+
+const template = (pack: string) => `
+import { Tab, Tabs } from 'rspress/theme';
+
+<Tabs>
+  <Tab label="pnpm">
+\`\`\`bash
+pnpm add ${pack}
+\`\`\`
+  </Tab>
+  <Tab label="npm">
+\`\`\`bash
+npm install --save ${pack}
+\`\`\`
+  </Tab>
+</Tabs>
+`;
+
+export default function plugin(..._configOptions: any) {
+  return (node: NodeMeta) => {
+    if (node.children) {
+      for (const index in node.children) {
+        const { lang, type } = node.children[index];
+
+        if (type === 'code' && lang === 'depsInstall') {
+          node.children[index].value = template(node.children[index].value);
+        }
+      }
+    }
+  };
+}

apps/docs/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@accelint/docs",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "build:deps": "pnpm run build:ladle && pnpm run build:typedoc",
+    "build:ladle": "pnpm --filter=@accelint/design-system exec ladle build -o ../../apps/docs/src/public/ladle --base ladle",
+    "build:typedoc": "typedoc",
+    "build": "pnpm run build:deps && rspress build",
+    "check": "biome check --write",
+    "dev": "pnpm run build:deps && rspress dev",
+    "format": "biome format --write",
+    "preview": "rspress preview"
+  },
+  "dependencies": {
+    "@accelint/design-system": "workspace:*",
+    "@rspress/plugin-playground": "^1.38.0",
+    "@types/node": "^18.19.67",
+    "react": "^18.3.1",
+    "rspress": "^1.37.3",
+    "typedoc": "0.27.6",
+    "typedoc-plugin-markdown": "4.3.3",
+    "typescript": "^5.7.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.3"
+  }
+}

apps/docs/rspress.config.ts

@@ -0,0 +1,30 @@
+import * as path from 'node:path';
+
+import { pluginPlayground } from '@rspress/plugin-playground';
+import { defineConfig } from 'rspress/config';
+
+// import customInstallBlock from './lib/plugin-remark-custom-install.ts';
+
+export default defineConfig({
+  markdown: {
+    // TODO: figure out if we can change the markdown before it is processed into rendered react components
+    // ... this solution seems to have been executed after that occurred; this would require more integration
+    // with AST generation of tree nodes in the processing pipeline of RSPress
+    // remarkPlugins: [
+    //   [
+    //     customInstallBlock,
+    //     // { foo: 1 }, // config options
+    //   ],
+    // ],
+    showLineNumbers: true,
+  },
+  plugins: [
+    pluginPlayground({
+      defaultDirection: 'vertical',
+      defaultRenderMode: 'pure', // or 'playground'
+    }),
+  ],
+  outDir: path.join(__dirname, 'dist'),
+  root: path.join(__dirname, 'src'),
+  title: 'DevTK',
+});

apps/docs/src/index.md

@@ -0,0 +1,7 @@
+# Welcome
+
+The DevTK project serves as a centralized repository for all reusable code modules that do not provide a competitive advantage or differentiating factors. This enables Accelint companies to accelerate product development through economies of scale through code reuse.
+
+There are two high-level categories that modules fall into: [Design System Components](packages/design-system) (and utilities) and data transformation libraries (everything else).
+
+[Explore Packages](packages/)

apps/docs/src/packages/constants.md

@@ -0,0 +1 @@
+# /constants

apps/docs/src/packages/constants/coordinates.md

@@ -0,0 +1 @@
+# /constants/coordinates

apps/docs/src/packages/constants/identifiers.md

@@ -0,0 +1 @@
+# /constants/identifiers

apps/docs/src/packages/converters.md

@@ -0,0 +1,3 @@
+# Converters
+
+The converter - utility - functions are centralized functionality for consistent value conversion logic across all projects.

apps/docs/src/packages/converters/azimuth-to-cardinal.md

@@ -0,0 +1 @@
+# /converters/azimuth-to-cardinal