fix: fix docs

.husky/.gitignore

@@ -1 +1 @@
-_
+_

.yo-rc.json

@@ -3,6 +3,7 @@
     "addedFilesSafe": {
       ".eslintrc.js": "661c7c22fbe2a894f22ac1e32568d3faa6f760c3",
       "docs/.vuepress/config.js": "88d80937f65fd1a32bda8b35ca3a5101cbaf4f8c",
+      "docs/nav.02.api/01.typedoc-iframe.md": "de3fe9eeebedcc31abeef79c3e2eb9ad8b19ac5b",
       "jest.config.js": "0bd134f06add10c42a03e4b115aef2a323e4b136",
       "lint-staged.config.js": "cbb09ecb17251589a793f69fea1a59c20f82a2c5",
       "prettier.config.js": "2339672f6e5b8d3aeebe63b98613dca158b8b650",
@@ -22,18 +23,19 @@
           "main": "dist/index.js",
           "repository": "ozum/pg-structure",
           "scripts.build": "npm run not-sync && tsc --incremental",
-          "scripts.docs:build": "npm-run-all -p typedoc:md typedoc:html && rm -rf docs/nav.02.api docs/.vuepress/public/api-site && mv api-docs-md docs/nav.02.api && mv api-docs-html docs/.vuepress/public/api-site && cp module-files/vuepress/01.typedoc-iframe.md docs/nav.02.api/ && NODE_ENV=production vuepress build docs",
-          "scripts.docs:dev": "vuepress dev docs",
+          "scripts.docs:build": "npm run tsmod vuepress-api && NODE_ENV=production vuepress build docs",
+          "scripts.docs:dev": "npm run tsmod vuepress-api && vuepress dev docs",
           "scripts.execute": "ts-node --transpile-only --compiler-options '{ \"module\": \"commonjs\" }'",
           "scripts.format": "prettier . --write",
           "scripts.lint": "eslint --ignore-path .gitignore --cache --max-warnings 0 --ext js,jsx,ts,tsx,vue --fix .",
-          "scripts.not-sync": "node module-files/scripts/tsmod.js not-sync dist,node_modules,coverage",
+          "scripts.not-sync": "npm run tsmod not-sync not-sync dist,node_modules,coverage",
           "scripts.postinstall": "is-ci || (husky install && npm run not-sync)",
           "scripts.postpublish": "pinst --enable",
           "scripts.prepublishOnly": "pinst --disable",
           "scripts.readme": "node module-files/scripts/tsmod.js readme",
           "scripts.release": "npm run readme && git pull && git add -A && git commit && git push --follow-tags",
           "scripts.test": "npm run not-sync && jest --coverage",
+          "scripts.tsmod": "node module-files/scripts/tsmod.js",
           "scripts.watch": "ts-node-dev --no-notify --respawn --transpile-only --compiler-options '{ \"module\": \"commonjs\" }'",
           "scripts.yo:update": "yo tsmod:uninstall --no-install --force && yo 'tsmod' '--vuepress' '--github-workflow' 'pg'",
           "types": "dist/index.d.ts"
@@ -57,13 +59,13 @@
           "devDependencies.eslint-plugin-import": "^2.22.0",
           "devDependencies.eslint-plugin-jest": "^24.1.3",
           "devDependencies.eslint-plugin-prettier": "^3.3.1",
-          "devDependencies.husky": "^5.0.7",
+          "devDependencies.husky": "^5.0.8",
           "devDependencies.is-ci": "^2.0.0",
           "devDependencies.jest": "^26.6.3",
           "devDependencies.lint-staged": "^10.5.3",
           "devDependencies.not-sync": "^1.2.0",
           "devDependencies.npm-run-all": "^4.1.5",
-          "devDependencies.pinst": "^2.1.2",
+          "devDependencies.pinst": "^2.1.4",
           "devDependencies.prettier": "^2.2.1",
           "devDependencies.readmeasy": "^0.2.7",
           "devDependencies.ts-jest": "^26.2.0",
@@ -74,7 +76,7 @@
           "devDependencies.typedoc-plugin-markdown": "^3.4.5",
           "devDependencies.typescript": "^4.1.3",
           "devDependencies.vuepress": "^1.8.0",
-          "devDependencies.vuepress-bar": "^0.3.2",
+          "devDependencies.vuepress-bar": "^0.3.3",
           "devDependencies.walkdir": "^0.4.1"
         }
       }

module-files/configs/vuepress-config.js

@@ -4,11 +4,18 @@ const packageData = require("../../package.json");
 
 const GOOGLE_ANALYTICS_ID = packageData.vuepress && packageData.vuepress["google-analytics-id"];
 
-const { nav, sidebar } = getVuePressBars(join(__dirname), "../../docs/.vuepress");
+const { nav, sidebar } = getVuePressBars(join(__dirname, "../../docs"), { addReadMeToFirstGroup: false });
 const plugins = ["@vuepress/active-header-links", "@vuepress/pwa"];
 
 if (GOOGLE_ANALYTICS_ID) plugins.push(["@vuepress/google-analytics", { ga: GOOGLE_ANALYTICS_ID }]);
 
+// If `addReadMeToFirstGroup` is `true`, and another link is not added API sidebar, it moves root README.md into first available section.
+// Below conditional code reverses this for api section by moving README.md link from children of classes (or first section) to main section.
+// if (sidebar["/nav.02.api/"][0].children) {
+//   sidebar["/nav.02.api/"][0].children.shift();
+//   sidebar["/nav.02.api/"].unshift("");
+// }
+
 module.exports = {
   title: packageData.label || packageData.name,
   description: packageData.description,

module-files/scripts/tsmod.js

@@ -50,7 +50,7 @@ async function spawn(cmd, args, options) {
  * @param out is output directory or file for generated markdown.
  * @param singleFile is whether to combine all output into single markdown file.
  */
-async function md({ out, singleFile }) {
+async function md({ out, singleFile = false }) {
   // rm -rf api-docs-md && typedoc  --plugin typedoc-plugin-example-tag,typedoc-plugin-markdown --excludeExternals --excludePrivate --excludeProtected --exclude 'src/bin/**/*' --theme markdown --readme none --out api-docs-md src/index.ts && find api-docs-md -name \"index.md\" -exec sh -c 'mv \"$1\" \"${1%index.md}\"index2.md' - {} \\;
   // const cwd = getCwd();
   const bin = join(cwd, "node_modules/.bin/typedoc");
@@ -72,14 +72,16 @@ async function md({ out, singleFile }) {
     getTypeDocEntry(),
   ];
 
-  if (hasDependency("vuepress")) options.unshift("--platform", "vuepress");
-
   try {
     await spawn(bin, options, { stdio: "inherit" });
 
-    // Rename all "index.md" files as "index2.md"
+    // Rename all "index.md" files as "index2.md", because VuePress treats "index.md" special. Renaming does not matter, because title comes from front-matter.
     const createdFiles = await walk.async(tmpDir);
-    createdFiles.filter((file) => basename(file) === "index.md").forEach((file) => fs.rename(file, join(dirname(file), "index2.md")));
+    await Promise.all(createdFiles.map((file) => addFrontMatterToMd(file)));
+
+    await Promise.all(
+      createdFiles.filter((file) => basename(file) === "index.md").map((file) => fs.rename(file, join(dirname(file), "index2.md")))
+    );
   } catch (error) {
     if (singleFile) await fs.rmdir(tmpDir, { recursive: true });
     throw error;
@@ -95,6 +97,26 @@ async function md({ out, singleFile }) {
   }
 }
 
+/**
+ * Add "front-matter" title to given markdown file using first level 1 title.
+ *
+ * @param {string} file is the file to add front matter title.
+ */
+async function addFrontMatterToMd(file) {
+  try {
+    const content = await fs.readFile(file, { encoding: "utf8" });
+    // If file has front-matter (---) do not touch.
+    if (content.match(new RegExp("^s+---"))) return;
+
+    // "# Class: User" results in "User". "# User" results in "User".
+    const firstTitleMatch = content.match(new RegExp("^[^#]+?#\\s+(.+?)\\r?\\n", "s"));
+    const firstTitle = firstTitleMatch !== null && firstTitleMatch[1] ? firstTitleMatch[1].replace(/.+?:\s+/, "") : undefined;
+    if (firstTitle) await fs.writeFile(file, `---\ntitle: ${firstTitle}\n---\n\n${content}`);
+  } catch (error) {
+    if (error.code !== "EISDIR") throw error;
+  }
+}
+
 /**
  * Creates TypeDoc HTML files from TypeScript source files.
  *
@@ -135,15 +157,15 @@ async function readme() {
 async function vuepressApi() {
   // npm-run-all -p typedoc:md typedoc:html && rm -rf docs/nav.02.api docs/.vuepress/public/api-site && mv api-docs-md docs/nav.02.api && mv api-docs-html docs/.vuepress/public/api-site && cp assets/typedoc/01.typedoc-iframe.md docs/nav.02.api/ && NODE_ENV=production vuepress build docs
 
-  // const cwd = getCwd();
   const mdPath = join(cwd, "docs/nav.02.api");
   const htmlPath = join(cwd, "docs/.vuepress/public/api-site");
-  const iframePath = join(cwd, "module-files/01.typedoc-iframe.md");
+  const iframePath = join(cwd, "module-files/vuepress/01.typedoc-iframe.md");
 
   await Promise.all([md({ out: mdPath }), html({ out: htmlPath })]);
+  // await md({ out: mdPath });
+  // await html({ out: htmlPath });
+  await fs.mkdir(mdPath, { recursive: true });
   await fs.copyFile(iframePath, join(mdPath, basename(iframePath))); // Don't put this in `Promise.all` with `md` and `html`. It needs first directory created. Otherwise file is copied same name with directory, since there is no directory yet.
-  // await intermodular.targetModule.execute("vuepress", ["build", "docs"], { env: { NODE_ENV: "production" } });
-  // intermodular.log("info", "VuePress site updated.");
 }
 
 /**

package.json

@@ -40,12 +40,13 @@
     "test": "npm run not-sync && jest --coverage",
     "readme": "node module-files/scripts/tsmod.js readme",
     "build": "npm run not-sync && tsc --incremental",
+    "docs:build": "npm run tsmod vuepress-api && NODE_ENV=production vuepress build docs",
+    "docs:dev": "npm run tsmod vuepress-api && vuepress dev docs",
     "postinstall": "is-ci || (husky install && npm run not-sync)",
-    "postpublish": "pinst --enable",
-    "docs:build": "npm-run-all -p typedoc:md typedoc:html && rm -rf docs/nav.02.api docs/.vuepress/public/api-site && mv api-docs-md docs/nav.02.api && mv api-docs-html docs/.vuepress/public/api-site && cp module-files/vuepress/01.typedoc-iframe.md docs/nav.02.api/ && NODE_ENV=production vuepress build docs",
-    "docs:dev": "vuepress dev docs",
-    "not-sync": "node module-files/scripts/tsmod.js not-sync dist,node_modules,coverage",
     "prepublishOnly": "pinst --disable",
+    "postpublish": "pinst --enable",
+    "not-sync": "npm run tsmod not-sync not-sync dist,node_modules,coverage",
+    "tsmod": "node module-files/scripts/tsmod.js",
     "yo:update": "yo tsmod:uninstall --no-install --force && yo 'tsmod' '--vuepress' '--github-workflow' 'pg'"
   },
   "vuepress": {
@@ -85,14 +86,14 @@
     "eslint-plugin-import": "^2.22.0",
     "eslint-plugin-jest": "^24.1.3",
     "eslint-plugin-prettier": "^3.3.1",
-    "husky": "^5.0.7",
+    "husky": "^5.0.8",
     "is-ci": "^2.0.0",
     "jest": "^26.6.3",
     "lint-staged": "^10.5.3",
     "not-sync": "^1.2.0",
     "npm-run-all": "^4.1.5",
     "pg-test-util": "^2.0.6",
-    "pinst": "^2.1.2",
+    "pinst": "^2.1.4",
     "prettier": "^2.2.1",
     "readmeasy": "^0.2.7",
     "ts-jest": "^26.2.0",
@@ -103,7 +104,7 @@
     "typedoc-plugin-markdown": "^3.4.5",
     "typescript": "^4.1.3",
     "vuepress": "^1.8.0",
-    "vuepress-bar": "^0.3.2",
+    "vuepress-bar": "^0.3.3",
     "walkdir": "^0.4.1"
   }
 }