Merge pull request #4612 from mermaid-js/sidv/docsVersion

Support MERMAID_RELEASE_VERSION in docs.

.github/pull_request_template.md

@@ -13,6 +13,6 @@ Describe the way your implementation works or what design decisions you made if
 Make sure you
 
 - [ ] :book: have read the [contribution guidelines](https://github.com/mermaid-js/mermaid/blob/develop/CONTRIBUTING.md)
-- [ ] :computer: have added unit/e2e tests (if appropriate)
-- [ ] :notebook: have added documentation (if appropriate)
+- [ ] :computer: have added necessary unit/e2e tests.
+- [ ] :notebook: have added documentation. Make sure [`MERMAID_RELEASE_VERSION`](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/docs/community/development.md#3-update-documentation) is used for all new features.
 - [ ] :bookmark: targeted `develop` branch

.github/workflows/build-docs.yml

@@ -1,6 +1,10 @@
 name: Build Vitepress docs
 
 on:
+  push:
+    branches:
+      - master
+      - release/*
   pull_request:
   merge_group:
 
@@ -25,5 +29,9 @@ jobs:
       - name: Install Packages
         run: pnpm install --frozen-lockfile
 
+      - name: Verify release verion
+        if: ${{ github.event_name == 'push' && (github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/heads/release')) }}
+        run: pnpm --filter mermaid run docs:verify-version
+
       - name: Run Build
         run: pnpm --filter mermaid run docs:build:vitepress

.vscode/launch.json

@@ -17,7 +17,7 @@
       "name": "Docs generation",
       "type": "node",
       "request": "launch",
-      "args": ["src/docs.mts"],
+      "args": ["scripts/docs.cli.mts"],
       "runtimeArgs": ["--loader", "ts-node/esm"],
       "cwd": "${workspaceRoot}/packages/mermaid",
       "skipFiles": ["<node_internals>/**", "**/node_modules/**"],

docs/community/development.md

@@ -223,6 +223,9 @@ If the users have no way to know that things have changed, then you haven't real
 Likewise, if users don't know that there is a new feature that you've implemented, it will forever remain unknown and unused.
 
 The documentation has to be updated to users know that things have changed and added!
+If you are adding a new feature, add `(v<MERMAID_RELEASE_VERSION>+)` in the title or description. It will be replaced automatically with the current version number when the release happens.
+
+eg: `# Feature Name (v<MERMAID_RELEASE_VERSION>+)`
 
 We know it can sometimes be hard to code _and_ write user documentation.
 

packages/mermaid/package.json

@@ -25,14 +25,16 @@
   "scripts": {
     "clean": "rimraf dist",
     "docs:code": "typedoc src/defaultConfig.ts src/config.ts src/mermaidAPI.ts && prettier --write ./src/docs/config/setup",
-    "docs:build": "rimraf ../../docs && pnpm docs:spellcheck && pnpm docs:code && ts-node-esm src/docs.mts",
-    "docs:verify": "pnpm docs:spellcheck && pnpm docs:code && ts-node-esm src/docs.mts --verify",
-    "docs:pre:vitepress": "pnpm --filter ./src/docs prefetch && rimraf src/vitepress && pnpm docs:code && ts-node-esm src/docs.mts --vitepress && pnpm --filter ./src/vitepress install --no-frozen-lockfile --ignore-scripts",
+    "docs:build": "rimraf ../../docs && pnpm docs:spellcheck && pnpm docs:code && ts-node-esm scripts/docs.cli.mts",
+    "docs:verify": "pnpm docs:spellcheck && pnpm docs:code && ts-node-esm scripts/docs.cli.mts --verify",
+    "docs:pre:vitepress": "pnpm --filter ./src/docs prefetch && rimraf src/vitepress && pnpm docs:code && ts-node-esm scripts/docs.cli.mts --vitepress && pnpm --filter ./src/vitepress install --no-frozen-lockfile --ignore-scripts",
     "docs:build:vitepress": "pnpm docs:pre:vitepress && (cd src/vitepress && pnpm run build) && cpy --flat src/docs/landing/ ./src/vitepress/.vitepress/dist/landing",
-    "docs:dev": "pnpm docs:pre:vitepress && concurrently \"pnpm --filter ./src/vitepress dev\" \"ts-node-esm src/docs.mts --watch --vitepress\"",
-    "docs:dev:docker": "pnpm docs:pre:vitepress && concurrently \"pnpm --filter ./src/vitepress dev:docker\" \"ts-node-esm src/docs.mts --watch --vitepress\"",
+    "docs:dev": "pnpm docs:pre:vitepress && concurrently \"pnpm --filter ./src/vitepress dev\" \"ts-node-esm scripts/docs.cli.mts --watch --vitepress\"",
+    "docs:dev:docker": "pnpm docs:pre:vitepress && concurrently \"pnpm --filter ./src/vitepress dev:docker\" \"ts-node-esm scripts/docs.cli.mts --watch --vitepress\"",
     "docs:serve": "pnpm docs:build:vitepress && vitepress serve src/vitepress",
     "docs:spellcheck": "cspell --config ../../cSpell.json \"src/docs/**/*.md\"",
+    "docs:release-version": "ts-node-esm scripts/update-release-version.mts",
+    "docs:verify-version": "ts-node-esm scripts/update-release-version.mts --verify",
     "types:build-config": "ts-node-esm --transpileOnly scripts/create-types-from-json-schema.mts",
     "types:verify-config": "ts-node-esm scripts/create-types-from-json-schema.mts --verify",
     "release": "pnpm build",

packages/mermaid/scripts/docs.cli.mts

@@ -0,0 +1,3 @@
+import { processDocs } from './docs.mjs';
+
+void processDocs();

packages/mermaid/scripts/docs.mts

@@ -27,8 +27,6 @@
  *   get their absolute paths. Ensures that the location of those 2 directories is not dependent on
  *   where this file resides.
  *
- * @todo Write a test file for this. (Will need to be able to deal .mts file. Jest has trouble with
- *   it.)
  */
 // @ts-ignore: we're importing internal jsonschema2md functions
 import { default as schemaLoader } from '@adobe/jsonschema2md/lib/schemaProxy.js';
@@ -55,9 +53,9 @@ import mm from 'micromatch';
 import flatmap from 'unist-util-flatmap';
 import { visit } from 'unist-util-visit';
 
-const MERMAID_MAJOR_VERSION = (
-  JSON.parse(readFileSync('../mermaid/package.json', 'utf8')).version as string
-).split('.')[0];
+export const MERMAID_RELEASE_VERSION = JSON.parse(readFileSync('../mermaid/package.json', 'utf8'))
+  .version as string;
+const MERMAID_MAJOR_VERSION = MERMAID_RELEASE_VERSION.split('.')[0];
 const CDN_URL = 'https://cdn.jsdelivr.net/npm'; // 'https://unpkg.com';
 
 const MERMAID_KEYWORD = 'mermaid';
@@ -80,7 +78,7 @@ const vitepress: boolean = process.argv.includes('--vitepress');
 const noHeader: boolean = process.argv.includes('--noHeader') || vitepress;
 
 // These paths are from the root of the mono-repo, not from the mermaid subdirectory
-const SOURCE_DOCS_DIR = 'src/docs';
+export const SOURCE_DOCS_DIR = 'src/docs';
 const FINAL_DOCS_DIR = vitepress ? 'src/vitepress' : '../../docs';
 
 const LOGMSG_TRANSFORMED = 'transformed';
@@ -167,7 +165,7 @@ const copyTransformedContents = (filename: string, doCopy = false, transformedCo
   logWasOrShouldBeTransformed(fileInFinalDocDir, doCopy);
 };
 
-const readSyncedUTF8file = (filename: string): string => {
+export const readSyncedUTF8file = (filename: string): string => {
   return readFileSync(filename, 'utf8');
 };
 
@@ -360,7 +358,7 @@ const transformMarkdown = (file: string) => {
 /**
  * Transforms the given JSON Schema into Markdown documentation
  */
-async function transormJsonSchema(file: string) {
+async function transformJsonSchema(file: string) {
   const yamlContents = readSyncedUTF8file(file);
   const jsonSchema = load(yamlContents, {
     filename: file,
@@ -506,7 +504,7 @@ const transformHtml = (filename: string) => {
   copyTransformedContents(filename, !verifyOnly, formattedHTML);
 };
 
-const getGlobs = (globs: string[]): string[] => {
+export const getGlobs = (globs: string[]): string[] => {
   globs.push('!**/dist/**', '!**/redirect.spec.ts', '!**/landing/**', '!**/node_modules/**');
   if (!vitepress) {
     globs.push(
@@ -520,12 +518,12 @@ const getGlobs = (globs: string[]): string[] => {
   return globs;
 };
 
-const getFilesFromGlobs = async (globs: string[]): Promise<string[]> => {
+export const getFilesFromGlobs = async (globs: string[]): Promise<string[]> => {
   return await globby(globs, { dot: true });
 };
 
 /** Main method (entry point) */
-const main = async () => {
+export const processDocs = async () => {
   if (verifyOnly) {
     console.log('Verifying that all files are in sync with the source files');
   }
@@ -535,7 +533,7 @@ const main = async () => {
 
   if (vitepress) {
     console.log(`${action} 1 .schema.yaml file`);
-    await transormJsonSchema('src/schemas/config.schema.yaml');
+    await transformJsonSchema('src/schemas/config.schema.yaml');
   } else {
     // skip because this creates so many Markdown files that it lags git
     console.log('Skipping 1 .schema.yaml file');
@@ -603,5 +601,3 @@ const main = async () => {
       });
   }
 };
-
-void main();

packages/mermaid/scripts/update-release-version.mts

@@ -0,0 +1,53 @@
+/* eslint-disable no-console */
+
+/**
+ * @file Update the MERMAID_RELEASE_VERSION placeholder in the documentation source files with the current version of mermaid.
+ * So contributors adding new features will only have to add the placeholder and not worry about updating the version number.
+ *
+ */
+import { posix } from 'path';
+import {
+  getGlobs,
+  getFilesFromGlobs,
+  SOURCE_DOCS_DIR,
+  readSyncedUTF8file,
+  MERMAID_RELEASE_VERSION,
+} from './docs.mjs';
+import { writeFile } from 'fs/promises';
+
+const verifyOnly: boolean = process.argv.includes('--verify');
+const versionPlaceholder = '<MERMAID_RELEASE_VERSION>';
+
+const main = async () => {
+  const sourceDirGlob = posix.join('.', SOURCE_DOCS_DIR, '**');
+  const mdFileGlobs = getGlobs([posix.join(sourceDirGlob, '*.md')]);
+  mdFileGlobs.push('!**/community/development.md');
+  const mdFiles = await getFilesFromGlobs(mdFileGlobs);
+  mdFiles.sort();
+  const mdFilesWithPlaceholder: string[] = [];
+  for (const mdFile of mdFiles) {
+    const content = readSyncedUTF8file(mdFile);
+    if (content.includes(versionPlaceholder)) {
+      mdFilesWithPlaceholder.push(mdFile);
+    }
+  }
+
+  if (mdFilesWithPlaceholder.length === 0) {
+    return;
+  }
+
+  if (verifyOnly) {
+    console.log(
+      `${mdFilesWithPlaceholder.length} file(s) were found with the placeholder ${versionPlaceholder}. Run \`pnpm --filter mermaid docs:release-version\` to update them.`
+    );
+    process.exit(1);
+  }
+
+  for (const mdFile of mdFilesWithPlaceholder) {
+    const content = readSyncedUTF8file(mdFile);
+    const newContent = content.replace(versionPlaceholder, MERMAID_RELEASE_VERSION);
+    await writeFile(mdFile, newContent);
+  }
+};
+
+void main();

packages/mermaid/src/docs/community/development.md

@@ -212,6 +212,9 @@ If the users have no way to know that things have changed, then you haven't real
 Likewise, if users don't know that there is a new feature that you've implemented, it will forever remain unknown and unused.
 
 The documentation has to be updated to users know that things have changed and added!
+If you are adding a new feature, add `(v<MERMAID_RELEASE_VERSION>+)` in the title or description. It will be replaced automatically with the current version number when the release happens.
+
+eg: `# Feature Name (v<MERMAID_RELEASE_VERSION>+)`
 
 We know it can sometimes be hard to code _and_ write user documentation.