js-build-tools 6.4.1 → 6.5.0

package/README.md

@@ -561,6 +561,9 @@ Add the following to the exports in your `build-tools.config.json`:
     // The directory holding the source, each folder in it becomes a module (TypeDoc) or is scanned recursively (jsdoc).
     // jsdoc also takes a list of directories and files, for example ["functions", "gulpfile.base.mjs"]
     "from": "src",
+    // Generate the documentation as part of build (the default). Set it to false to only generate it when you run
+    // the docs task yourself (see below)
+    "inBuild": true,
     // The markdown file used as the front page of the documentation (a short overview of your project)
     "index": "MAIN.md",
     // 'typedoc' or 'jsdoc'. Left out (or false), it's inferred from typescript.enabled - 'typedoc' when your
@@ -582,6 +585,20 @@ While `docs.enabled` is on, `gulp build` generates the documentation instead of
 hand-written (a short overview which links to the documentation). If you also export `docs` from your gulpfile you can
 run it on its own with `gulp docs`, and can then add the script `"docs": "gulp docs"`.
 
+To make generating the documentation a deliberate step instead, set `docs.inBuild` to `false`: `gulp build` then
+generates neither the documentation nor the readme, and `gulp docs` is the only thing that writes to `docs.to`. This
+suits a `docs.to` which points into another repository (a website, say): a build on a work-in-progress branch no
+longer rewrites the published documentation, which you regenerate when you release instead. For example with
+release-it, in `.release-it.json`:
+
+```json
+{
+  "hooks": {
+    "after:bump": "npm run docs"
+  }
+}
+```
+
 ### Browser automation (optional)
 
 Unlike the rest of this file, this isn't a `build-tools.config.json`-driven feature with its own task - it's a pair

package/dist/build.js

@@ -1,73 +1,76 @@
-"use strict";
-
-require("core-js/modules/esnext.weak-map.delete-all.js");
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.build = void 0;
-var _bundle = require("./bundle.js");
-var _bundleMinify = require("./bundleMinify.js");
-var _partials = require("./partials.js");
-var _compileReadme = require("./compileReadme.js");
-var _typeDocs = require("./typeDocs.js");
-var _jsdocDocs = require("./jsdocDocs.js");
-var _distMinify = require("./distMinify.js");
-var _sourceLint = require("./sourceLint.js");
-var _gulp = require("gulp");
-var gulpConfig = _interopRequireWildcard(require("../gulp.config.js"));
-var _copyFonts = require("./copyFonts.js");
-var _images = require("./images.js");
-var _resolveDocsMethod = require("./partials/resolveDocsMethod.js");
-var _sass = require("./sass.js");
-var _testFull = require("./testFull.js");
-var cache;
-function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var r, c, a = Object.defineProperty, n = { __proto__: null, default: e }; if (Object(e) !== e) return n; if (cache || "function" != typeof WeakMap || (cache = new WeakMap()), cache) { if (cache.has(e)) return cache.get(e); cache.set(e, n); } for (c in e) "default" !== c && {}.hasOwnProperty.call(e, c) && ((r = a && Object.getOwnPropertyDescriptor(e, c)) && (r.get || r.set) ? a(n, c, r) : n[c] = e[c]); return n; }
+"use strict";
+
+require("core-js/modules/esnext.weak-map.delete-all.js");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.build = void 0;
+var _bundle = require("./bundle.js");
+var _bundleMinify = require("./bundleMinify.js");
+var _partials = require("./partials.js");
+var _compileReadme = require("./compileReadme.js");
+var _typeDocs = require("./typeDocs.js");
+var _jsdocDocs = require("./jsdocDocs.js");
+var _distMinify = require("./distMinify.js");
+var _sourceLint = require("./sourceLint.js");
+var _gulp = require("gulp");
+var gulpConfig = _interopRequireWildcard(require("../gulp.config.js"));
+var _copyFonts = require("./copyFonts.js");
+var _images = require("./images.js");
+var _resolveDocsMethod = require("./partials/resolveDocsMethod.js");
+var _sass = require("./sass.js");
+var _testFull = require("./testFull.js");
+var cache;
+function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var r, c, a = Object.defineProperty, n = { __proto__: null, default: e }; if (Object(e) !== e) return n; if (cache || "function" != typeof WeakMap || (cache = new WeakMap()), cache) { if (cache.has(e)) return cache.get(e); cache.set(e, n); } for (c in e) "default" !== c && {}.hasOwnProperty.call(e, c) && ((r = a && Object.getOwnPropertyDescriptor(e, c)) && (r.get || r.set) ? a(n, c, r) : n[c] = e[c]); return n; }
 /**
  * Runs several processes to build and validate the project.
  * Cleans and lints the source, distributes and minifies, bundles and minifies, creates the readme, then runs the
  * tests.
  * @memberOf module:js-build-tools
  * @returns {stream.Stream}
- */
-const build = (done = null) => {
-  const buildActions = [(0, _partials.distSeries)(), _distMinify.distMinify];
-  const generateDocs = gulpConfig.get('docs.enabled');
-  const docsMethod = (0, _resolveDocsMethod.resolveDocsMethod)();
-  if (generateDocs) {
-    // The documentation is generated from the source itself, the readme is written by hand
-    buildActions.push(docsMethod === 'jsdoc' ? _jsdocDocs.jsdocDocs : _typeDocs.typeDocs);
-  } else if (gulpConfig.get('typescript.enabled')) {
-    // For ts usage, we need to run the readme on the dist directly since that is where the .js files are located
-    buildActions.push(_compileReadme.compileReadme);
-  }
-  if (gulpConfig.get('browser.enabled')) {
-    // If not 'nodeOnly' then we also want to bundle for browser after we complete the dist directory
-    buildActions.push(_bundle.bundle);
-    buildActions.push(_bundleMinify.bundleMinify);
-  }
-  const runActions = [(0, _gulp.series)(...buildActions)];
-  if (!generateDocs && !gulpConfig.get('typescript.enabled')) {
-    // Since we didn't run this in series after dist because of typescript, we need to run it now. Potentially faster here.
-    runActions.push(_compileReadme.compileReadme);
-  }
-  runActions.push(_testFull.testFull);
-  if (gulpConfig.get('fonts.enabled')) {
-    // Conditionally add Fonts process
-    runActions.push(_copyFonts.copyFonts);
-  }
-  if (gulpConfig.get('images.enabled')) {
-    // Conditionally add Images process
-    runActions.push(_images.images);
-  }
-  if (gulpConfig.get('sass.enabled')) {
-    // Conditionally add SASS process
-    runActions.push(_sass.sass);
-  }
-  // clean has to finish before anything writes into the output folders - images, fonts and sass all write into
-  // browser/, so running clean in parallel with them races (ENOTEMPTY errors from clean, or output deleted mid-write).
-  // sourceLint fixes the real source in place before anything compiles from it (distSeries, tsFor inside it), so a
-  // build never reads a mix of pre- and post-fix content; clean only touches dist/browser output, so the two can
-  // run alongside each other.
-  return (0, _gulp.series)((0, _gulp.parallel)(_partials.clean, _sourceLint.sourceLint), (0, _gulp.parallel)(...runActions))(done);
-};
+ */
+const build = (done = null) => {
+  const buildActions = [(0, _partials.distSeries)(), _distMinify.distMinify];
+  const generateDocs = gulpConfig.get('docs.enabled');
+  const docsMethod = (0, _resolveDocsMethod.resolveDocsMethod)();
+  if (generateDocs) {
+    // The documentation is generated from the source itself, the readme is written by hand. With docs.inBuild off,
+    // generating it is left to the standalone docs task (gulp docs), so a build never rewrites it.
+    if (gulpConfig.get('docs.inBuild') !== false) {
+      buildActions.push(docsMethod === 'jsdoc' ? _jsdocDocs.jsdocDocs : _typeDocs.typeDocs);
+    }
+  } else if (gulpConfig.get('typescript.enabled')) {
+    // For ts usage, we need to run the readme on the dist directly since that is where the .js files are located
+    buildActions.push(_compileReadme.compileReadme);
+  }
+  if (gulpConfig.get('browser.enabled')) {
+    // If not 'nodeOnly' then we also want to bundle for browser after we complete the dist directory
+    buildActions.push(_bundle.bundle);
+    buildActions.push(_bundleMinify.bundleMinify);
+  }
+  const runActions = [(0, _gulp.series)(...buildActions)];
+  if (!generateDocs && !gulpConfig.get('typescript.enabled')) {
+    // Since we didn't run this in series after dist because of typescript, we need to run it now. Potentially faster here.
+    runActions.push(_compileReadme.compileReadme);
+  }
+  runActions.push(_testFull.testFull);
+  if (gulpConfig.get('fonts.enabled')) {
+    // Conditionally add Fonts process
+    runActions.push(_copyFonts.copyFonts);
+  }
+  if (gulpConfig.get('images.enabled')) {
+    // Conditionally add Images process
+    runActions.push(_images.images);
+  }
+  if (gulpConfig.get('sass.enabled')) {
+    // Conditionally add SASS process
+    runActions.push(_sass.sass);
+  }
+  // clean has to finish before anything writes into the output folders - images, fonts and sass all write into
+  // browser/, so running clean in parallel with them races (ENOTEMPTY errors from clean, or output deleted mid-write).
+  // sourceLint fixes the real source in place before anything compiles from it (distSeries, tsFor inside it), so a
+  // build never reads a mix of pre- and post-fix content; clean only touches dist/browser output, so the two can
+  // run alongside each other.
+  return (0, _gulp.series)((0, _gulp.parallel)(_partials.clean, _sourceLint.sourceLint), (0, _gulp.parallel)(...runActions))(done);
+};
 exports.build = build;

package/dist/build.min.js

@@ -1 +1 @@
-"use strict";require("core-js/modules/esnext.weak-map.delete-all.js"),Object.defineProperty(exports,"__esModule",{value:!0}),exports.build=void 0;var cache,_bundle=require("./bundle.js"),_bundleMinify=require("./bundleMinify.js"),_partials=require("./partials.js"),_compileReadme=require("./compileReadme.js"),_typeDocs=require("./typeDocs.js"),_jsdocDocs=require("./jsdocDocs.js"),_distMinify=require("./distMinify.js"),_sourceLint=require("./sourceLint.js"),_gulp=require("gulp"),gulpConfig=_interopRequireWildcard(require("../gulp.config.js")),_copyFonts=require("./copyFonts.js"),_images=require("./images.js"),_resolveDocsMethod=require("./partials/resolveDocsMethod.js"),_sass=require("./sass.js"),_testFull=require("./testFull.js");function _interopRequireWildcard(e,s){if(!s&&e&&e.__esModule)return e;var i,r,t=Object.defineProperty,l={__proto__:null,default:e};if(Object(e)!==e)return l;if(cache||"function"!=typeof WeakMap||(cache=new WeakMap),cache){if(cache.has(e))return cache.get(e);cache.set(e,l)}for(r in e)"default"!==r&&{}.hasOwnProperty.call(e,r)&&((i=t&&Object.getOwnPropertyDescriptor(e,r))&&(i.get||i.set)?t(l,r,i):l[r]=e[r]);return l}const build=(e=null)=>{const s=[(0,_partials.distSeries)(),_distMinify.distMinify],i=gulpConfig.get("docs.enabled"),r=(0,_resolveDocsMethod.resolveDocsMethod)();i?s.push("jsdoc"===r?_jsdocDocs.jsdocDocs:_typeDocs.typeDocs):gulpConfig.get("typescript.enabled")&&s.push(_compileReadme.compileReadme),gulpConfig.get("browser.enabled")&&(s.push(_bundle.bundle),s.push(_bundleMinify.bundleMinify));const t=[(0,_gulp.series)(...s)];return i||gulpConfig.get("typescript.enabled")||t.push(_compileReadme.compileReadme),t.push(_testFull.testFull),gulpConfig.get("fonts.enabled")&&t.push(_copyFonts.copyFonts),gulpConfig.get("images.enabled")&&t.push(_images.images),gulpConfig.get("sass.enabled")&&t.push(_sass.sass),(0,_gulp.series)((0,_gulp.parallel)(_partials.clean,_sourceLint.sourceLint),(0,_gulp.parallel)(...t))(e)};exports.build=build;
+"use strict";require("core-js/modules/esnext.weak-map.delete-all.js"),Object.defineProperty(exports,"__esModule",{value:!0}),exports.build=void 0;var cache,_bundle=require("./bundle.js"),_bundleMinify=require("./bundleMinify.js"),_partials=require("./partials.js"),_compileReadme=require("./compileReadme.js"),_typeDocs=require("./typeDocs.js"),_jsdocDocs=require("./jsdocDocs.js"),_distMinify=require("./distMinify.js"),_sourceLint=require("./sourceLint.js"),_gulp=require("gulp"),gulpConfig=_interopRequireWildcard(require("../gulp.config.js")),_copyFonts=require("./copyFonts.js"),_images=require("./images.js"),_resolveDocsMethod=require("./partials/resolveDocsMethod.js"),_sass=require("./sass.js"),_testFull=require("./testFull.js");function _interopRequireWildcard(e,s){if(!s&&e&&e.__esModule)return e;var i,r,t=Object.defineProperty,l={__proto__:null,default:e};if(Object(e)!==e)return l;if(cache||"function"!=typeof WeakMap||(cache=new WeakMap),cache){if(cache.has(e))return cache.get(e);cache.set(e,l)}for(r in e)"default"!==r&&{}.hasOwnProperty.call(e,r)&&((i=t&&Object.getOwnPropertyDescriptor(e,r))&&(i.get||i.set)?t(l,r,i):l[r]=e[r]);return l}const build=(e=null)=>{const s=[(0,_partials.distSeries)(),_distMinify.distMinify],i=gulpConfig.get("docs.enabled"),r=(0,_resolveDocsMethod.resolveDocsMethod)();i?!1!==gulpConfig.get("docs.inBuild")&&s.push("jsdoc"===r?_jsdocDocs.jsdocDocs:_typeDocs.typeDocs):gulpConfig.get("typescript.enabled")&&s.push(_compileReadme.compileReadme),gulpConfig.get("browser.enabled")&&(s.push(_bundle.bundle),s.push(_bundleMinify.bundleMinify));const t=[(0,_gulp.series)(...s)];return i||gulpConfig.get("typescript.enabled")||t.push(_compileReadme.compileReadme),t.push(_testFull.testFull),gulpConfig.get("fonts.enabled")&&t.push(_copyFonts.copyFonts),gulpConfig.get("images.enabled")&&t.push(_images.images),gulpConfig.get("sass.enabled")&&t.push(_sass.sass),(0,_gulp.series)((0,_gulp.parallel)(_partials.clean,_sourceLint.sourceLint),(0,_gulp.parallel)(...t))(e)};exports.build=build;

package/functions/build.mjs

@@ -26,8 +26,11 @@ export const build = (done = null) => {
   const generateDocs = gulpConfig.get('docs.enabled')
   const docsMethod = resolveDocsMethod()
   if (generateDocs) {
-    // The documentation is generated from the source itself, the readme is written by hand
-    buildActions.push(docsMethod === 'jsdoc' ? jsdocDocs : typeDocs)
+    // The documentation is generated from the source itself, the readme is written by hand. With docs.inBuild off,
+    // generating it is left to the standalone docs task (gulp docs), so a build never rewrites it.
+    if (gulpConfig.get('docs.inBuild') !== false) {
+      buildActions.push(docsMethod === 'jsdoc' ? jsdocDocs : typeDocs)
+    }
   } else if (gulpConfig.get('typescript.enabled')) {
     // For ts usage, we need to run the readme on the dist directly since that is where the .js files are located
     buildActions.push(compileReadme)

package/functions/build.test.mjs

@@ -676,6 +676,29 @@ describe('build', () => {
     })
   }, 30000)
 
+  test('with docs.inBuild off, build generates neither the documentation nor the readme', done => {
+    const readmePath = gulpConfig.get('readme.to')
+    const readmeFile = gulpConfig.get('readme.file')
+    fs.rmSync(`${readmePath}/${readmeFile}`, { force: true })
+    typeDocs.mockClear()
+    jsdocDocs.mockClear()
+    gulpConfig.set('browser.enabled', false)
+    gulpConfig.set('typescript.enabled', false)
+    gulpConfig.set('docs.enabled', true)
+    gulpConfig.set('docs.inBuild', false)
+    expect.assertions(4)
+    build(() => {
+      gulpConfig.set('docs.enabled', false)
+      gulpConfig.set('docs.inBuild', true)
+      expect(jsdocDocs).not.toHaveBeenCalled()
+      expect(typeDocs).not.toHaveBeenCalled()
+      // The readme is still written by hand while docs.enabled is on
+      expect(fs.existsSync(`${readmePath}/${readmeFile}`)).toBe(false)
+      expect(testFull).toHaveBeenCalled()
+      done()
+    })
+  }, 30000)
+
   test('docs.method overrides the typescript.enabled inference either way', done => {
     const srcPath = gulpConfig.get('srcPath')
     const rootPath = gulpConfig.get('rootPath')

package/gulp.config.mjs

@@ -135,6 +135,9 @@ import { fileExists } from 'test-filesystem'
  * build does this instead of generating the readme from the jsdoc comments of the compiled files.
  * @property {ArrayableSetting} from - The directory holding the source, each folder in it becomes a module (TypeDoc) or
  * is scanned recursively (jsdoc). jsdoc also takes a list of directories and files.
+ * @property {BooleanSetting} inBuild - Generate the documentation as part of build (the default). Turn it off to only
+ * generate it when you run the docs task yourself (gulp docs), for example when docs.to points into another
+ * repository and you only want to publish the documentation of a release.
  * @property {StringSetting} index - The markdown file used as the front page of the documentation.
  * @property {StringSetting} logLevel - How much TypeDoc reports: Verbose, Info, Warn, Error or None. Not used by jsdoc.
  * @property {FlagStringSetting} method - 'typedoc' or 'jsdoc'. False (the default) infers it from typescript.enabled -
@@ -216,6 +219,7 @@ const setDefaults = {
   docs: {
     enabled: false,
     from: 'src',
+    inBuild: true,
     index: 'MAIN.md',
     logLevel: 'Warn',
     method: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-build-tools",
-  "version": "6.4.1",
+  "version": "6.5.0",
   "description": "Standardised build process with gulp.",
   "main": "gulpfile.base.js",
   "exports": {