@leverege/build-tools 2.58.4 → 2.58.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leverege/build-tools",
-  "version": "2.58.4",
+  "version": "2.58.6",
   "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",
@@ -81,7 +81,7 @@
     "readline-sync": "^1.4.10",
     "semver": "^7.6.3",
     "simple-git": "^3.27.0",
-    "zx": "^8.2.4"
+    "zx": "^8.3.0"
   },
   "devDependencies": {
     "@leverege/eslint-config-leverege": "^5.0.1",

package/src/Utils.mjs

@@ -477,7 +477,7 @@ export const analyzeRepository = async ( giveGuidance ) => {
     await shellCmd( 'npm run build' )
   }
 
-  const buildToolsVersion = closestPackageJson.devDependencies['@leverege/build-tools']
+  const buildToolsVersion = closestPackageJson.devDependencies['@leverege/build-tools'] || closestPackageJson.dependencies['@leverege/build-tools']
   if ( !buildToolsVersion ) {
     errorExit( 'Error: missing devDependency for @leverege/build-tools in package.json' )
   }

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
@@ -347,7 +347,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,15 +10,16 @@
   "templates": {
     "cleverLinks": true,
     "monospaceLinks": false,
+    "preserveDescriptions": true,
     "default": {
       "useLongnameInNav": true,
       "outputSourceFiles": false
     }
   },
   "opts": {
-    "template": "node_modules/@leverege/jsdoc-template",
     "encoding": "utf8",
-    "lenient": false
+    "lenient": false,
+    "markdown": true
   },
   "docdash": {
     "static": true,
@@ -30,10 +31,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,45 @@
  *   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`
+
+// build the location of the template file from the build-tools root
+// in order to avoid hardcoding in the jsdoc config file - this is
+// important in order to support running generate-docs from a user's
+// laptop or deployed to the doc-creator service on k8s
+const jsdocTemplate = `${BUILD_TOOLS_ROOT}/../../jsdoc-template`
 
-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} -t ${jsdocTemplate} -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 )
+}