Skip to content

Commit 915d1fe

Browse files
sidharthv96sidharthv96
committed
docs: Auto generate shape docs
Not keen on how it's currently run, open to suggestions on better ways.
1 parent 2f0f227 commit 915d1fe

File tree

8 files changed

+181
-95
lines changed

8 files changed

+181
-95
lines changed

‎.esbuild/docs.ts

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
import { execFileSync } from 'child_process';
2+
import { build } from 'esbuild';
3+
import { rm } from 'fs/promises';
4+
import { generateLangium } from '../.build/generateLangium.js';
5+
import type { MermaidBuildOptions } from './util.js';
6+
import { defaultOptions, getBuildConfig } from './util.js';
7+
8+
const buildDocs = async () => {
9+
const option: MermaidBuildOptions = {
10+
...defaultOptions,
11+
options: {
12+
file: 'rendering-util/rendering-elements/shapes.cli.ts',
13+
name: 'mermaid-shapes',
14+
packageName: 'mermaid',
15+
},
16+
} as const;
17+
18+
await build({ ...getBuildConfig(option), splitting: false, sourcemap: false });
19+
};
20+
21+
const handler = (e) => {
22+
// eslint-disable-next-line no-console
23+
console.error(e);
24+
process.exit(1);
25+
};
26+
27+
const main = async () => {
28+
await generateLangium();
29+
await buildDocs().catch(handler);
30+
execFileSync('node', ['packages/mermaid/dist/mermaid-shapes.esm.mjs']);
31+
await rm('packages/mermaid/dist/mermaid-shapes.esm.mjs');
32+
};
33+
34+
void main();

‎docs/syntax/flowchart.md

+49-47
Large diffs are not rendered by default.

‎packages/mermaid/.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,4 @@ README.*
44
src/docs/public/user-avatars/
55
src/docs/.vitepress/cache
66
src/docs/.vitepress/components.d.ts
7+
src/docs/syntax/shapesTable.md

‎packages/mermaid/package.json

+2-1
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,8 @@
3535
"clean": "rimraf dist",
3636
"dev": "pnpm -w dev",
3737
"docs:code": "typedoc src/defaultConfig.ts src/config.ts src/mermaid.ts && prettier --write ./src/docs/config/setup",
38-
"docs:build": "rimraf ../../docs && pnpm docs:spellcheck && pnpm docs:code && tsx scripts/docs.cli.mts",
38+
"docs:build": "rimraf ../../docs && pnpm docs:shapes && pnpm docs:spellcheck && pnpm docs:code && tsx scripts/docs.cli.mts",
39+
"docs:shapes": "cd ../.. && tsx .esbuild/docs.ts",
3940
"docs:verify": "pnpm docs:spellcheck && pnpm docs:code && tsx scripts/docs.cli.mts --verify",
4041
"docs:pre:vitepress": "pnpm --filter ./src/docs prefetch && rimraf src/vitepress && pnpm docs:code && tsx scripts/docs.cli.mts --vitepress && pnpm --filter ./src/vitepress install --no-frozen-lockfile --ignore-scripts",
4142
"docs:build:vitepress": "pnpm docs:pre:vitepress && (cd src/vitepress && pnpm run build) && cpy --flat src/docs/landing/ ./src/vitepress/.vitepress/dist/landing",

‎packages/mermaid/src/docs/syntax/flowchart.md

+2-47
Original file line numberDiff line numberDiff line change
@@ -212,53 +212,8 @@ This syntax creates a node A as a rectangle. It renders in the same way as `A["A
212212

213213
Below is a comprehensive list of the newly introduced shapes and their corresponding semantic meanings, short names, and aliases:
214214

215-
| **Semantic Name** | **Shape Name** | **Short Name** | **Description** | **Alias Supported** |
216-
| ------------------------------------- | ---------------------- | -------------- | ------------------------------ | -------------------------------------------------------------- |
217-
| **Process** | Rectangle | `rect` | Standard process shape | `proc`, `process`, `rectangle` |
218-
| **Event** | Rounded Rectangle | `rounded` | Represents an event | `event` |
219-
| **Terminal Point** | Stadium | `stadium` | Terminal point | `terminal`, `pill` |
220-
| **Subprocess** | Framed Rectangle | `fr-rect` | Subprocess | `subprocess`,`subproc`, `framed-rectangle`, `subroutine` |
221-
| **Database** | Cylinder | `cyl` | Database storage | `db`, `database`, `cylinder` |
222-
| **Start** | Circle | `circle` | Starting point | `circ` |
223-
| **Odd** | Odd | `odd` | Odd shape | |
224-
| **Decision** | Diamond | `diam` | Decision-making step | `decision`, `diamond` |
225-
| **Prepare Conditional** | Hexagon | `hex` | Preparation or condition step | `hexagon`, `prepare` |
226-
| **Data Input/Output** | Lean Right | `lean-r` | Represents input or output | `lean-right`, `in-out` |
227-
| **Data Input/Output** | Lean Left | `lean-l` | Represents output or input | `lean-left`, `out-in` |
228-
| **Priority Action** | Trapezoid Base Bottom | `trap-b` | Priority action | `priority`, `trapezoid-bottom` |
229-
| **Manual Operation** | Trapezoid Base Top | `trap-t` | Represents a manual task | `manual`, `trapezoid-top` |
230-
| **Stop** | Double Circle | `dbl-circ` | Represents a stop point | `double-circle` |
231-
| **Text Block** | Text Block | `text` | Text block | - |
232-
| **Card** | Notched Rectangle | `notch-rect` | Represents a card | `card`, `notched-rectangle` |
233-
| **Lined/Shaded Process** | Lined Rectangle | `lin-rect` | Lined process shape | `lined-rectangle`,`lined-process`, `lin-proc`,`shaded-process` |
234-
| **Start** | Small Circle | `sm-circ` | Small starting point | `start`, `small-circle` |
235-
| **Stop** | Framed Circle | `fr-circ` | Stop point | `stop`, `framed-circle` |
236-
| **Fork/Join** | Filled Rectangle | `fork` | Fork or join in process flow | `join` |
237-
| **Collate** | Hourglass | `hourglass` | Represents a collate operation | `hourglass` |
238-
| **Comment** | Curly Brace | `brace` | Adds a comment | `comment`, `brace-l` |
239-
| **Comment Right** | Curly Brace | `brace-r` | Adds a comment | - |
240-
| **Comment with braces on both sides** | Curly Braces | `braces` | Adds a comment | - |
241-
| **Com Link** | Lightning Bolt | `bolt` | Communication link | `com-link`, `lightning-bolt` |
242-
| **Document** | Document | `doc` | Represents a document | `doc`, `document` |
243-
| **Delay** | Half-Rounded Rectangle | `delay` | Represents a delay | `half-rounded-rectangle` |
244-
| **Direct Access Storage** | Horizontal Cylinder | `h-cyl` | Direct access storage | `das`, `horizontal-cylinder` |
245-
| **Disk Storage** | Lined Cylinder | `lin-cyl` | Disk storage | `disk`, `lined-cylinder` |
246-
| **Display** | Curved Trapezoid | `curv-trap` | Represents a display | `curved-trapezoid`, `display` |
247-
| **Divided Process** | Divided Rectangle | `div-rect` | Divided process shape | `div-proc`, `divided-rectangle`, `divided-process` |
248-
| **Extract** | Triangle | `tri` | Extraction process | `extract`, `triangle` |
249-
| **Internal Storage** | Window Pane | `win-pane` | Internal storage | `internal-storage`, `window-pane` |
250-
| **Junction** | Filled Circle | `f-circ` | Junction point | `junction`, `filled-circle` |
251-
| **Lined Document** | Lined Document | `lin-doc` | Lined document | `lined-document` |
252-
| **Loop Limit** | Trapezoidal Pentagon | `notch-pent` | Loop limit step | `loop-limit`, `notched-pentagon` |
253-
| **Manual File** | Flipped Triangle | `flip-tri` | Manual file operation | `manual-file`, `flipped-triangle` |
254-
| **Manual Input** | Sloped Rectangle | `sl-rect` | Manual input step | `manual-input`, `sloped-rectangle` |
255-
| **Multi-Document** | Stacked Document | `docs` | Multiple documents | `documents`, `st-doc`, `stacked-document` |
256-
| **Multi-Process** | Stacked Rectangle | `st-rect` | Multiple processes | `procs`, `processes`, `stacked-rectangle` |
257-
| **Paper Tape** | Flag | `flag` | Paper tape | `paper-tape` |
258-
| **Stored Data** | Bow Tie Rectangle | `bow-rect` | Stored data | `stored-data`, `bow-tie-rectangle` |
259-
| **Summary** | Crossed Circle | `cross-circ` | Summary | `summary`, `crossed-circle` |
260-
| **Tagged Document** | Tagged Document | `tag-doc` | Tagged document | `tag-doc`, `tagged-document` |
261-
| **Tagged Process** | Tagged Rectangle | `tag-rect` | Tagged process | `tagged-rectangle`,`tag-proc`, `tagged-process` |
215+
<!-- Will be auto generated with `pnpm --filter mermaid docs:shapes` -->
216+
<!--@include: ./shapesTable.md -->
262217

263218
### Example Flowchart with New Shapes
264219

‎packages/mermaid/src/rendering-util/rendering-elements/shapes.cli.ts

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
import { writeFile } from 'fs/promises';
2+
import { buildShapeDoc } from './shapesDoc.js';
3+
4+
export const writeShapeDoc = async () => {
5+
await writeFile('packages/mermaid/src/docs/syntax/shapesTable.md', buildShapeDoc());
6+
};
7+
8+
void writeShapeDoc();

0 commit comments

Comments
 (0)