Looking for examples of practical scripts

[danaoira]

Hello! I was wondering if you could help with some examples of practical npm run scripts?

I had to dig through other repos to find examples of how they set up their npm run docs script.

Some of the ones I'm interested in are:

1. Recursively check all folders for .js files & write into one file: `jsdoc2md ".src/{,**}/.js" > ./README.me"
2. For each folder, create a single .md file of all .js files in the folder

Thanks in advance!
Dana

[eddeee888]

Hello Dana,

For the first case, is it not working for you? I have done something similar to this before and it worked 🤔

For the second use case, I think I have a similar use case for my project: I have a folder containing all my plugin folders and each plugin folder needs an .md.

Here's roughly what the script looks like:

"use strict";
const jsdoc2md = require("jsdoc-to-markdown");
const fs = require("fs");
const path = require("path");
const dmd = require("dmd");

// This is where the root plugin folder is, relative to this script
const pluginsRootDir = [__dirname, "..", "..", "packages", "core", "src", "plugins"];

// Create an array containing  plugin folders
const pluginModules = fs.readdirSync(path.join(...pluginsRootDir));

// Go through plugin folders and create an array of objects containing the plugin name and path
const plugins = pluginModules.map((pluginName) => ({
  pathArray: [...pluginsRootDir, pluginName],
  pluginName,
}));

// Go through plugin folders and generate an .md file for each folder
plugins.forEach(({ pathArray, pluginName }) => {
  
  // I'm parsing TypeScript files but your can replace it with `*.js` if needed
  const files = path.join(...[...pathArray, "**", "*.ts"]);
  
  jsdoc2md.getJsdocData({ files: files, configure: "./jsdoc2md.json" });

  const templateData = jsdoc2md.getTemplateDataSync({ files: files });
  const output = dmd(templateData);

  fs.writeFileSync(path.join(...[...pathArray, `${pluginName}.md`]), output);
});

Here's where I'm currently using it: https://github.com/eddeee888/route-codegen/blob/master/scripts/docs/generate-docs.js
Each plugin folder should have an .md inside: https://github.com/eddeee888/route-codegen/tree/master/packages/core/src/plugins
Hope this helps!

[75lb]

Hi Dana.. personally, the majority of my npm run scripts are fairly trivial, something like:

jsdoc2md --template readme.hbs --files index.js lib/*.js > README.md

or, if the rendered API docs are too large for the readme:

jsdoc2md --files index.js lib/*.js > docs/API.md

In general, I try to keep the API surface of my projects fairly minimal so rarely have meaty API docs or a requirement to do anything fancy.