Add API documentation generation

Author: viroulep

functions/functions.js

@@ -1,22 +1,24 @@
+const categories = [
+  { name: 'array' },
+  { name: 'boolean' },
+  { name: 'cluster' },
+  { name: 'display' },
+  { name: 'events' },
+  { name: 'groups' },
+  { name: 'help' },
+  { name: 'math' },
+  { name: 'persons' },
+  { name: 'sheets' },
+  { name: 'staff' },
+  { name: 'table' },
+  { name: 'time' },
+  { name: 'tuple' },
+  { name: 'udf' },
+  { name: 'util' },
+  { name: 'wcif', docs: 'This category gathers all functions regarding high level WCIF manipulation' },
+]
+
 module.exports = {
-  allFunctions:
-      [].concat(
-          require('./array').functions,
-          require('./boolean').functions,
-          require('./cluster').functions,
-          require('./display').functions,
-          require('./events').functions,
-          require('./groups').functions,
-          require('./help').functions,
-          require('./math').functions,
-          require('./persons').functions,
-          require('./sheets').functions,
-          require('./staff').functions,
-          require('./table').functions,
-          require('./time').functions,
-          require('./tuple').functions,
-          require('./udf').functions,
-          require('./util').functions,
-          require('./wcif').functions,
-      )
+  categories,
+  allFunctions: categories.flatMap(c => require(`./${c.name}`).functions)
 }

gen_docs_api.js

@@ -0,0 +1,88 @@
+const dotenv = require('dotenv')
+const env = process.env.ENV || 'DEV'
+dotenv.config({ path: '.env.' + env })
+
+const functions = require('./functions/functions')
+const categories = functions.categories.filter(c => c.name !== 'display')
+
+const functionToAnchorName = (name, genericParams) => {
+  if (typeof this.generated === 'undefined') {
+    this.generated = []
+  }
+  const baseName = `${name.toLowerCase()}${genericParams ? genericParams.map(t => t.toLowerCase()).join('-') : ''}`
+  let suffix = 1
+  let generatedName = baseName
+  while (this.generated.includes(generatedName)) {
+    generatedName = `${baseName}-${suffix++}`
+  }
+  this.generated.push(generatedName)
+  return generatedName
+}
+
+const functionName = (name, genericParams) => `${name}${genericParams ? `\\<${genericParams.join(', ')}>` : ''}`
+
+const stringForArg = ({ name, type, defaultValue, nullable, canBeExternal, repeated, lazy, docs }) => {
+  const properties = []
+  if (nullable) {
+    properties.push('(can be null)')
+  }
+  if (canBeExternal) {
+    properties.push('(can be external)')
+  }
+  if (repeated) {
+    properties.push('(variadic)')
+  }
+  if (lazy) {
+    properties.push('(lazy evaluated)')
+  }
+  const propertiesString = properties.length > 0 ? ` *${properties.join('')}*` : ''
+  const helpForArg = docs ? `
+
+      ${docs}` : ''
+
+  return `    - *${type.replace('<', '\\<')}* **${name}**${defaultValue !== undefined ? `=${defaultValue}`:''}${propertiesString}${helpForArg}`
+}
+
+const stringForFunction = ({ name, genericParams, docs, outputType, args, mutations}) => `
+### ${functionName(name, genericParams)}
+
+${docs || 'TODO'}
+
+  - Args:${args.length === 0 ? ' none' : `\n${args.map(stringForArg).join('\n')}`}
+
+  - Returns: **${outputType.replace('<', '\\<')}**
+
+  - WCIF changes: **${mutations && mutations.length > 0 ? `${mutations.join(', ')}` : 'none'}**`
+
+const documentation = categories.map(({ name, docs }) => {
+  const functions = require(`./functions/${name}.js`).functions
+  return `## ${name}
+
+${docs || 'TODO'}
+
+${functions.map(stringForFunction).join('\n')}
+`
+}).join('\n')
+
+const tocFunction = ({ name, genericParams }) => `    - [${functionName(name, genericParams)}](#${functionToAnchorName(name, genericParams)})`
+const toc = categories.map(({ name }) => {
+  const functions = require(`./functions/${name}.js`).functions
+  return `  - [${name}](#${name})
+${functions.map(tocFunction).join('\n')}`
+}).join('\n')
+
+const { exec } = require('node:child_process')
+
+exec('git log -1 --oneline | cut -d " " -f 1 | tr -d "\n"', (_, stdout ) => {
+
+  console.log(`# CompScript API reference
+
+*This documentation was automatically generated on commit [${stdout}](https://github.com/cubingusa/compscript/commit/${stdout}) with \`npm run gen-docs-api\`, don't edit this file directly.*
+
+## Index
+
+${toc}
+
+${documentation}`)
+})
+

package.json

@@ -19,6 +19,7 @@
   "main": "main.js",
   "scripts": {
     "dev-server": "ENV=DEV npx nodemon -i wcif_data .",
+    "gen-docs-api": "node ./gen_docs_api.js > docs/api.md",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "repository": {