Search code examples
javascriptjsdoc

Adding static files to JSDoc

I need to add static resources for tutorials in JSDoc. Structure of my project is:

PROJECT ROOT 
| 
|
---> Project directory A
---> Project directory B
---> ...
|
---> Tutorials
     |
     |
     |
     -------->IMG

Directory tutorials/img contains static resources I want to include. My conf file is:

{
  "tags": {
    "allowUnknownTags": true,
    "dictionaries": [
      "jsdoc",
      "closure"
    ]
  },
  "source": {
    "include": [
      "modules/abstractModel.js",
      "modules/abstractMediator.js",
      "modules/abstractTemplate.js",
      "modules/abstractView.js",
      "modules/modelEvent/modelEvent.js"
    ],
    //"exclude": ["http/httpSession.js", "http/wyPlayWrapper.js", "util/service.js"],
    "includePattern": ".+\\.js(doc)?$",
    "excludePattern": "(^|\\/|\\\\)_"
  },
  "plugins": [],

  "templates": {
    "default": {
      "staticFiles": {
        "include": ["./trunk/tutorials/img/"]
      }
    }
  }
}

This is the command line I use to produce documentation (executed from shell into PROJECT ROOT dir):

jsdoc -c conf/jsdoc.conf -u tutorials/ -d ./docs . tutorials/README.md --verbose

But any static file is imported into docs folder, and I cannot use any image in tutorial. Any suggestion is appreciated.

Solution

  • The feature seems to be very buggy, at least in release JSDoc 3.3.0-dev (Mon, 30 Jun 2014 00:12:06 GMT).

    First of all, the correct syntax seems to be:

    {
  ....

  "templates": {
    "default": {
      "staticFiles": {
        "paths": ["./tutorials/img/"]
      }
    }
  }
}

    Then, in the file jsdoc/templates/default/publish.js, I changed line ~525 from

    var sourcePath = fs.toDir(filePath);

    to

    var sourcePath = fs.toDir(fileName);

    In this way, files from tutorials/img are copied into docs outdir itself. It is not the best solution (subdirectories aren't copied), but it is enough for my purposes.