Allow master configuration file for all tutorials

[eethann]

I'm embarking on a new, fairly large, project that will be using jsDoc, and I'm reluctant to create a separate json file for each markdown tutorial file. It seems a bit tedious and also hard to work with.

My preference would be for a single json file, say tutorials.conf.json, that I could put into my tutorial directory and use to organize my tutorials via structured json objects, with the property names being the identifier for each tutorial. I'm thinking something along the lines of

{
  "sometopic" : {
    "title" : "Some Topic!",
    "children" : [
      "sometopicchild",
      "someothertopicchild"
    ]
  },
  "anothertopic" : {
    "title" : "etc"
  }
}

Is there some reason such a system would not be advised?

If it seems like a feasible possibility (maybe as an alternative syntax, keeping the current) I'm happy to try my hand at a bit of patching, though any recommendations on approach or places to look would be welcomed.

[mathematicalcoffee]

Perhaps the tutorial finder could do something like:

/** checks if `conf` contains the metadata for a single tutorial or not.
 * @param {object} conf - the object to check (typically from JSON.parse(some file))
 */
function isSingleTutorial(conf) {
    // if conf.title exists or conf.children exists, it is metadata for a single tutorial
    return (conf.hasOwnProperty('title') || conf.hasOwnProperty('children'));
}

Then in lib/jsdoc/tutorials/resolver.js, function exports.load (where it loads the configuration file):

// configuration file
case 'json':
    var meta = JSON.parse(content);
    if (isSingleTutorial(meta)) {
        // proceed as before
        conf[name] = meta;
    } else {
        // loop through each child of meta and if isSingleTutorial(meta[child]),
        // then conf[child] = meta[child];
    }

Alternatively, perhaps there could be a designated filename for the index (like index.json) and if that file exists, then it is treated as containing information about multiple tutorials instead of just about one tutorial.

[hegemonic]

I agree that this would be a useful enhancement, and the solution proposed by @mathematicalcoffee sounds good.

While we're at it, perhaps we could allow the children property to contain either:

1. An array of strings, which represent the identifiers for other tutorials.
2. An object whose keys are identifiers, and whose values define tutorials.

That way you could do something like this, which allows the JSON structure to match the tutorial structure:

{
  "sometopic": {
    "title": "Some Topic!",
    "children": {
      "sometopicchild": {
          "title": "Whatta Topic!"
      },
      "someothertopicchild": {
          "title": "You Gotta See This Topic!"
      }
    }
  }
}

(We could always do that later as a follow-on improvement, too.)

[mathematicalcoffee]

OK I'll work on this.

Should I assume that only the dedicated filename index.json contains information for multiple tutorials, or should I allow any json to have multiple tutorials in it (I suspect the latter - if you had many tutorials it could be handy to split index.json into a few different files e.g. index.faqs.json, index.walkthroughs.json, ...)