Add readme-building utility script

Author: marijnh

bin/build-readme.js

@@ -0,0 +1,59 @@
+// Function to build github-proof readmes that contain the package's API
+// docs as HTML.
+
+const {core, nonCore} = require("./packages")
+const {gather, gatherMany} = require("gettypes")
+const {build, browserImports} = require("builddocs")
+const {join} = require("path"), fs = require("fs")
+
+exports.buildReadme = function(pkg) {
+  let imports = [type => {
+    let sibling = type.typeSource && core.find(name => type.typeSource.startsWith("../" + name + "/"))
+    if (sibling) return "https://codemirror.net/6/docs/ref#" + sibling + "." + type.type
+  }, type => {
+    if (/\blezer[\/-]tree\b/.test(type.typeSource)) return `https://lezer.codemirror.net/docs/ref/#tree.${type.type}`
+    if (/\blezer\b/.test(type.typeSource)) return `https://lezer.codemirror.net/docs/ref/#lezer.${type.type}`
+    if (/\bstyle-mod\b/.test(type.typeSource)) return "https://github.com/marijnh/style-mod#documentation"
+  }, browserImports]
+
+  let template = fs.readFileSync(join(pkg.dir, pkg.name == "legacy-modes" ? "mode" : "src", "README.md"), "utf8")
+  let html = ""
+
+  if (pkg.name == "legacy-modes") {
+    let mods = fs.readdirSync(join(pkg.dir, "mode")).filter(f => /\.d.ts$/.test(f)).map(file => {
+      let name = /^(.*)\.d\.ts$/.exec(file)[1]
+      return {name, filename: join(pkg.dir, "mode", file), basedir: pkg.dir}
+    }), items = gatherMany(mods)
+    for (let i = 0; i < mods.length; i++) {
+      let {name} = mods[i]
+      html += `\n<h3 id="${name}">mode/<a href="#${name}">${name}</a></h3>\n` + build({
+        name: pkg.name,
+        anchorPrefix: name + ".",
+        allowUnresolvedTypes: false,
+        imports
+      }, items[i])
+    }
+    template += "\n$$$"
+  } else {
+    let placeholders = /\n@[^]*@\w+|\n@\w+/.exec(template)
+    html = build({
+      mainText: placeholders[0],
+      name: pkg.name,
+      anchorPrefix: "",
+      allowUnresolvedTypes: false,
+      imports
+    }, gather({filename: pkg.main, basedir: pkg.dir}))
+    template = template.slice(0, placeholders.index) + "\n$$$" + template.slice(placeholders.index + placeholders[0].length)
+  }
+
+  html = html.replace(/<\/?span.*?>/g, "")
+    .replace(/id="(.*?)"/g, (_, id) => `id="user-content-${id.toLowerCase()}"`)
+    .replace(/href="#(.*?)"/g, (_, id) => {
+      let first = /^[^^.]*/.exec(id)[0]
+      if (core.includes(first)) return `href="https://codemirror.net/6/docs/ref/#${id}"`
+      if (first == pkg.name && id.length > first.length) id = id.slice(first.length + 1)
+      return `href="#user-content-${id.toLowerCase()}"`
+    })
+
+  return template.replace("$$$", html)
+}

bin/cm.js

@@ -6,7 +6,7 @@ const child = require("child_process"), fs = require("fs"), fsp = fs.promises, p
 
 let root = join(__dirname, "..")
 
-const {loadPackages} = require("./packages")
+const {loadPackages, nonCore} = require("./packages")
 
 let {packages, packageNames, buildPackages} = loadPackages()
 
@@ -24,6 +24,7 @@ function start() {
     commit,
     push,
     grep,
+    "build-readme": buildReadme,
     run: runCmd,
     "--help": () => help(0)
   }[command]
@@ -33,13 +34,14 @@ function start() {
 
 function help(status) {
   console.log(`Usage:
-  cm install [--ssh]      Clone and symlink the packages, install dependencies, build
+  cm install [--ssh]      Clone and symlink the packages, install deps, build
   cm packages             Emit a list of all pkg names
   cm build                Build the bundle files
   cm clean                Delete files created by the build
   cm devserver            Start a dev server on port 8090
   cm release <package> [--edit] [--version <version>]
                           Create commits to tag a release
+  cm build-readme <pkg>   Regenerate the readme file for a non-core package
   cm commit <args>        Run git commit in all packages that have changes
   cm push                 Run git push in packages that have new commits
   cm run <command>        Run the given command in each of the package dirs
@@ -387,4 +389,10 @@ function runCmd(cmd, ...args) {
   }
 }
 
+function buildReadme(name) {
+  if (!nonCore.includes(name)) help(1)
+  let pkg = packageNames[name]
+  fs.writeFileSync(join(pkg.dir, "README.md"), require("./build-readme").buildReadme(pkg))
+}
+
 start()

bin/packages.js

@@ -57,6 +57,7 @@ class Pkg {
     }
   }
 }
+exports.Pkg = Pkg
 
 exports.loadPackages = function loadPackages() {
   let packages = exports.all.map(n => new Pkg(n))

package.json

@@ -12,7 +12,9 @@
   "license": "(MIT OR GPL-3.0)",
   "devDependencies": {
     "@types/mocha": "^5.2.0",
+    "builddocs": "git://github.com/marijnh/builddocs.git#v1",
     "eslint4b-prebuilt": "^6.7.1",
+    "gettypes": "git://github.com/adrianheine/gettypes.git",
     "esmoduleserve": "^0.2.0",
     "mocha": "^7.1.1",
     "rollup": "^2.35.1",