|
| 1 | +import { readdirSync, readFileSync, existsSync } from 'node:fs'; |
| 2 | +import { resolve, dirname } from 'node:path'; |
| 3 | +import { fileURLToPath } from 'node:url'; |
| 4 | + |
| 5 | +/** |
| 6 | + * Auto-derived sidebars for the generated docs sections. |
| 7 | + * |
| 8 | + * Two trees feed this module: |
| 9 | + * |
| 10 | + * - `docs/api/` — docfx-generated reference for the public surface of |
| 11 | + * every shipped MTConnect.NET library. ~1800 type pages keyed by |
| 12 | + * `MTConnect.<Namespace>.<Type>.md`, plus a docfx-produced `toc.yml` |
| 13 | + * that lists each namespace and the types under it. We parse `toc.yml` |
| 14 | + * and build a hierarchical sidebar where namespace dots fold into |
| 15 | + * nested collapsible groups — so `MTConnect.Devices.DataItems.SampleDataItem` |
| 16 | + * lives at `MTConnect > Devices > DataItems > SampleDataItem`. |
| 17 | + * |
| 18 | + * - `docs/reference/` — Roslyn-generated narrative reference (CLI flags, |
| 19 | + * environment variables, configuration schema, HTTP API). A flat |
| 20 | + * alphabetical list keyed off whatever `.md` files the generator |
| 21 | + * emits, so a future page added by `MTConnect.NET-DocsGen` surfaces |
| 22 | + * in the sidebar without a config-side edit. |
| 23 | + * |
| 24 | + * Both functions are pure-fs reads; they run at VitePress config-load |
| 25 | + * time (which is before the dev server boots and before the build |
| 26 | + * traverses pages). The npm `predev` / `prebuild` hooks regenerate |
| 27 | + * both trees before VitePress reads them, so a fresh clone produces |
| 28 | + * a fully-populated sidebar on the first `npm run dev`. |
| 29 | + */ |
| 30 | + |
| 31 | +// VitePress sidebar shapes (loosely typed — VitePress accepts plain |
| 32 | +// objects, and pulling the official types would require an import that |
| 33 | +// VitePress' own config doesn't enforce). |
| 34 | +type SidebarItem = { |
| 35 | + text: string; |
| 36 | + link?: string; |
| 37 | + collapsed?: boolean; |
| 38 | + items?: SidebarItem[]; |
| 39 | +}; |
| 40 | + |
| 41 | +// Resolve paths relative to this file so the module works whether |
| 42 | +// VitePress is invoked from `docs/` or from the repo root. |
| 43 | +const here = dirname(fileURLToPath(import.meta.url)); |
| 44 | +const docsRoot = resolve(here, '..'); |
| 45 | + |
| 46 | +// ─── /api/ — docfx hierarchy ──────────────────────────────────────────────── |
| 47 | + |
| 48 | +// Internal tree node used while building the namespace hierarchy. |
| 49 | +// Each node represents one dot-segment in a namespace path. `types` |
| 50 | +// holds the leaf entries (sidebar items pointing at type pages); |
| 51 | +// `overview` is the namespace landing page link if one exists. |
| 52 | +type ApiNode = { |
| 53 | + children: Map<string, ApiNode>; |
| 54 | + types: SidebarItem[]; |
| 55 | + overview?: string; |
| 56 | +}; |
| 57 | + |
| 58 | +const makeNode = (): ApiNode => ({ children: new Map(), types: [] }); |
| 59 | + |
| 60 | +// Strip the `.md` extension and any leading `/` so the result is a |
| 61 | +// clean VitePress route, e.g. `MTConnect.Adapters.AgentClient.md` -> |
| 62 | +// `/api/MTConnect.Adapters.AgentClient`. |
| 63 | +const hrefToRoute = (href: string): string => |
| 64 | + `/api/${href.replace(/\.md$/, '')}`; |
| 65 | + |
| 66 | +// Minimal `toc.yml` parser. The docfx-emitted file is regular enough |
| 67 | +// that a line-oriented parse is robust and avoids pulling in a YAML |
| 68 | +// dependency. Schema: |
| 69 | +// |
| 70 | +// - name: <namespace> |
| 71 | +// href: <namespace>.md |
| 72 | +// items: |
| 73 | +// - name: Classes # section divider (no href) |
| 74 | +// - name: <type> |
| 75 | +// href: <namespace>.<type>.md |
| 76 | +// - name: Structs # next divider |
| 77 | +// ... |
| 78 | +// - name: <next namespace> |
| 79 | +// ... |
| 80 | +const parseToc = (content: string) => { |
| 81 | + const namespaces: Array<{ |
| 82 | + name: string; |
| 83 | + href: string; |
| 84 | + types: Array<{ name: string; href: string }>; |
| 85 | + }> = []; |
| 86 | + |
| 87 | + let current: (typeof namespaces)[number] | null = null; |
| 88 | + let pending: { name: string; href?: string } | null = null; |
| 89 | + let inItems = false; |
| 90 | + |
| 91 | + const flushPending = () => { |
| 92 | + if (!pending || !current || !pending.href) return; |
| 93 | + current.types.push({ name: pending.name, href: pending.href }); |
| 94 | + pending = null; |
| 95 | + }; |
| 96 | + |
| 97 | + for (const raw of content.split('\n')) { |
| 98 | + const line = raw.replace(/\r$/, ''); |
| 99 | + // Top-level namespace entry. |
| 100 | + let m = /^- name: (.+)$/.exec(line); |
| 101 | + if (m) { |
| 102 | + flushPending(); |
| 103 | + if (current) namespaces.push(current); |
| 104 | + current = { name: m[1], href: '', types: [] }; |
| 105 | + pending = null; |
| 106 | + inItems = false; |
| 107 | + continue; |
| 108 | + } |
| 109 | + // Top-level href for the namespace block currently being parsed. |
| 110 | + m = /^ {2}href: (.+)$/.exec(line); |
| 111 | + if (m && current && !inItems) { |
| 112 | + current.href = m[1]; |
| 113 | + continue; |
| 114 | + } |
| 115 | + if (/^ {2}items:$/.test(line)) { |
| 116 | + inItems = true; |
| 117 | + continue; |
| 118 | + } |
| 119 | + // Item-level entry inside the current namespace block. |
| 120 | + m = /^ {2}- name: (.+)$/.exec(line); |
| 121 | + if (m && inItems) { |
| 122 | + flushPending(); |
| 123 | + pending = { name: m[1] }; |
| 124 | + continue; |
| 125 | + } |
| 126 | + m = /^ {4}href: (.+)$/.exec(line); |
| 127 | + if (m && pending) { |
| 128 | + pending.href = m[1]; |
| 129 | + continue; |
| 130 | + } |
| 131 | + } |
| 132 | + flushPending(); |
| 133 | + if (current) namespaces.push(current); |
| 134 | + return namespaces; |
| 135 | +}; |
| 136 | + |
| 137 | +// Build the nested namespace tree by walking each namespace's |
| 138 | +// dot-separated path. Each segment becomes a child node; the final |
| 139 | +// segment receives the namespace's overview href and the type list. |
| 140 | +const buildApiTree = ( |
| 141 | + namespaces: ReturnType<typeof parseToc>, |
| 142 | +): ApiNode => { |
| 143 | + const root = makeNode(); |
| 144 | + for (const ns of namespaces) { |
| 145 | + const segments = ns.name.split('.'); |
| 146 | + let node = root; |
| 147 | + for (const segment of segments) { |
| 148 | + let child = node.children.get(segment); |
| 149 | + if (!child) { |
| 150 | + child = makeNode(); |
| 151 | + node.children.set(segment, child); |
| 152 | + } |
| 153 | + node = child; |
| 154 | + } |
| 155 | + if (ns.href) node.overview = hrefToRoute(ns.href); |
| 156 | + for (const t of ns.types) { |
| 157 | + node.types.push({ text: t.name, link: hrefToRoute(t.href) }); |
| 158 | + } |
| 159 | + } |
| 160 | + return root; |
| 161 | +}; |
| 162 | + |
| 163 | +// Case-insensitive locale comparator so groups and types sort |
| 164 | +// predictably regardless of underlying string ordering quirks |
| 165 | +// (e.g. uppercase ASCII grouping ahead of lowercase). |
| 166 | +const byTextCI = (a: SidebarItem, b: SidebarItem) => |
| 167 | + a.text.localeCompare(b.text, 'en', { sensitivity: 'base' }); |
| 168 | + |
| 169 | +// Recursively project the tree into VitePress sidebar items. A node |
| 170 | +// with children becomes a collapsible group; types are sorted into |
| 171 | +// the group alongside any nested child groups. The namespace overview |
| 172 | +// (if present) leads the group as an "Overview" entry. |
| 173 | +const projectNode = (segment: string, node: ApiNode): SidebarItem => { |
| 174 | + const items: SidebarItem[] = []; |
| 175 | + if (node.overview) { |
| 176 | + items.push({ text: 'Overview', link: node.overview }); |
| 177 | + } |
| 178 | + const typeItems = [...node.types].sort(byTextCI); |
| 179 | + const childItems = [...node.children.entries()] |
| 180 | + .map(([s, n]) => projectNode(s, n)) |
| 181 | + .sort(byTextCI); |
| 182 | + // Children (sub-namespaces) listed before types so the hierarchy |
| 183 | + // reads top-down: nested namespaces first, then the types declared |
| 184 | + // directly in this namespace. |
| 185 | + items.push(...childItems, ...typeItems); |
| 186 | + return { |
| 187 | + text: segment, |
| 188 | + collapsed: true, |
| 189 | + items, |
| 190 | + }; |
| 191 | +}; |
| 192 | + |
| 193 | +/** |
| 194 | + * Build the `/api/` sidebar from docfx's `toc.yml`. Returns a single |
| 195 | + * top-level "API reference" group whose items are the nested namespace |
| 196 | + * tree. Falls back to a one-entry "Overview" sidebar when the docfx |
| 197 | + * output is missing (e.g. a tree without `npm run regen` first). |
| 198 | + */ |
| 199 | +export const apiSidebar = (): SidebarItem[] => { |
| 200 | + const tocPath = resolve(docsRoot, 'api', 'toc.yml'); |
| 201 | + const overview: SidebarItem = { text: 'Overview', link: '/api/' }; |
| 202 | + if (!existsSync(tocPath)) { |
| 203 | + return [{ text: 'API reference', items: [overview] }]; |
| 204 | + } |
| 205 | + const namespaces = parseToc(readFileSync(tocPath, 'utf8')); |
| 206 | + const tree = buildApiTree(namespaces); |
| 207 | + const topLevel = [...tree.children.entries()] |
| 208 | + .map(([s, n]) => projectNode(s, n)) |
| 209 | + .sort(byTextCI); |
| 210 | + return [ |
| 211 | + { |
| 212 | + text: 'API reference', |
| 213 | + items: [overview, ...topLevel], |
| 214 | + }, |
| 215 | + ]; |
| 216 | +}; |
| 217 | + |
| 218 | +// ─── /reference/ — Roslyn-generated narrative ───────────────────────────── |
| 219 | + |
| 220 | +// Convert a file name like `environment-variables.md` to a sidebar |
| 221 | +// label like `Environment variables` (lower-case-with-hyphens to |
| 222 | +// sentence case, keeping mid-word capitals as-is for HTTP/CLI/etc.). |
| 223 | +const labelFor = (slug: string): string => { |
| 224 | + // Hand-tuned overrides for common acronyms / multi-cap labels. |
| 225 | + const overrides: Record<string, string> = { |
| 226 | + cli: 'CLI reference', |
| 227 | + 'http-api': 'HTTP API', |
| 228 | + 'environment-variables': 'Environment variables', |
| 229 | + configuration: 'Configuration schema', |
| 230 | + }; |
| 231 | + if (overrides[slug]) return overrides[slug]; |
| 232 | + const spaced = slug.replace(/-/g, ' '); |
| 233 | + return spaced.charAt(0).toUpperCase() + spaced.slice(1); |
| 234 | +}; |
| 235 | + |
| 236 | +/** |
| 237 | + * Build the `/reference/` sidebar by listing every `.md` file under |
| 238 | + * `docs/reference/` except `index.md` (which is wired in as the |
| 239 | + * "Overview" entry). Pages sort alphabetically by displayed label, |
| 240 | + * so a new generator output appears without a config-side edit. |
| 241 | + */ |
| 242 | +export const referenceSidebar = (): SidebarItem[] => { |
| 243 | + const refRoot = resolve(docsRoot, 'reference'); |
| 244 | + const items: SidebarItem[] = [ |
| 245 | + { text: 'Overview', link: '/reference/' }, |
| 246 | + ]; |
| 247 | + if (existsSync(refRoot)) { |
| 248 | + const pages = readdirSync(refRoot) |
| 249 | + .filter((f) => f.endsWith('.md') && f !== 'index.md') |
| 250 | + .map((f) => { |
| 251 | + const slug = f.replace(/\.md$/, ''); |
| 252 | + return { text: labelFor(slug), link: `/reference/${slug}` }; |
| 253 | + }) |
| 254 | + .sort(byTextCI); |
| 255 | + items.push(...pages); |
| 256 | + } |
| 257 | + return [ |
| 258 | + { |
| 259 | + text: 'Auto-generated reference', |
| 260 | + items, |
| 261 | + }, |
| 262 | + ]; |
| 263 | +}; |
0 commit comments