@leverege/build-tools 2.58.4 → 2.58.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leverege/build-tools",
-  "version": "2.58.4",
+  "version": "2.58.5",
   "description": "A collection of build / support tools for Leverege developers",
   "main": "index.js",
   "repository": {
@@ -62,7 +62,7 @@
     "@google-cloud/artifact-registry": "^3.5.0",
     "@leverege/jsdoc-template": "^1.0.1",
     "ansi-colors": "^4.1.3",
-    "chalk": "^5.4.0",
+    "chalk": "^5.4.1",
     "command-line-args": "^6.0.1",
     "command-line-usage": "^7.0.3",
     "deepmerge": "^4.3.1",

package/src/circleate.sh

@@ -128,7 +128,7 @@ jobs:
           at: ~/project
       - run:
           name: Generate docs
-          command: npx jsdoc -r src -R README.md -d docs
+          command: npm run docs
       - store_artifacts:
           path: docs
           prefix: docs

package/src/generate-docs-conf.json

@@ -10,6 +10,7 @@
   "templates": {
     "cleverLinks": true,
     "monospaceLinks": false,
+    "preserveDescriptions": true,
     "default": {
       "useLongnameInNav": true,
       "outputSourceFiles": false
@@ -18,7 +19,8 @@
   "opts": {
     "template": "node_modules/@leverege/jsdoc-template",
     "encoding": "utf8",
-    "lenient": false
+    "lenient": false,
+    "markdown": true
   },
   "docdash": {
     "static": true,
@@ -30,10 +32,10 @@
     "scripts": [],
     "menu":{
       "Bitbucket": {
-	"href":"https://bitbucket.org/leverege/IF_THIS_MAKES_SENSE",
-	"target":"_blank",
-	"class":"menu-item",
-	"id":"repository"
+        "href":"https://bitbucket.org/leverege/IF_THIS_MAKES_SENSE",
+        "target":"_blank",
+        "class":"menu-item",
+        "id":"repository"
       }
     }
   }

package/src/generate-docs.mjs

@@ -7,23 +7,39 @@
  *   npx --package=jsdoc-to-markdown jsdoc2md --files src/*.js --configure ./jsdoc.json > docs/md/API.md
  *
  */
+import fs from 'node:fs'
+
 import {
-  condir,
+  BUILD_TOOLS_ROOT,
   debug,
+  err,
   getRepositoryDescr,
-  getSourceTop,
-  log,
   shellCmd,
 } from './Utils.mjs'
 
+const jsdocConfig = `${BUILD_TOOLS_ROOT}/generate-docs-conf.json`
 
-const jsdocTemplate = `${getSourceTop()}/jsdoc-template`
-const jsdocConfig = `${jsdocTemplate}/jsdoc.json`
+if ( !fs.existsSync( jsdocConfig ) ) { // eslint-disable-line security/detect-non-literal-fs-filename
+  err( `cannot find the jsdoc config file: ${jsdocConfig}` )
+  process.exit( 1 )
+}
 
 const repoDescr = await getRepositoryDescr()
 
-condir( { jsdocTemplate, jsdocConfig, repoDescr }, '<==The Repo' )
+debug( { jsdocConfig, repoDescr }, '<==The Repo' )
+
+// blow away any existing docs before recreating the docs dir
+if ( fs.existsSync( 'docs' ) ) {
+  fs.rmSync( 'docs', { recursive : true } )
+}
+fs.mkdirSync( 'docs/md', { recursive : true } )
 
-await shellCmd( `npx jsdoc -c ${jsdocConfig} -R README.md -d docs src` )
-await shellCmd( 'mkdir -p docs/md' )
-await shellCmd( `npx --package=jsdoc-to-markdown jsdoc2md --files src/*.js --configure ./jsdoc.json`, { stdout : { file : 'docs/md/API.md' } } )
+try {
+  await shellCmd( `npx --yes jsdoc -c ${jsdocConfig} -R README.md -d docs src` )
+  await shellCmd(
+    `npx --yes --package=jsdoc-to-markdown jsdoc2md --files src/*.js --configure ${jsdocConfig}`,
+    { stdout : { file : 'docs/md/API.md' } }
+  )
+} catch ( error ) {
+  err( error )
+}