docConfig

  • typedef
DocumentJS.docConfig

{Object}

 

Configures the behavior of DocumentJS. The following are values found within a documentjs.json or the grunt configuration.

Object

Properties

  1. versions {Object<String,projectConfig | String>}Optional

    A map of version names to their source or to a projectConfig that specifies where and how to install the release. For example:

    {
  "versions" : {
    "1.8.4": "https://github.com/org/project/tree/v1.8.4",
    "2.0.9": "https://github.com/org/project/tree/v2.0.9"
    "3.0.0-pre": {
      "source": "https://github.com/org/project#major",
      "npmInstall": true
    }
  }
}

    Each versions key is a version name and the value is either a projectConfig or will be made into a projectConfig's source.

    Each version will be downloaded to a location depending on versionDest, defaultDest and defaultVersion. If the version key equals defaultVersion the project will be installed using defaultDest; otherwise, the project will be installed using versionDest.

  2. defaultVersion {String}Optional

    The default version that will be copied into the defaultDest location. This is so users can go to http://site.com/api to find the latest docs and not http://site.com/2.0.1/api.

  3. defaultDest="./<%=name%>" {String}Optional

    The location of where the default docs should be rendered to.

  4. versionDest="./<%=version%>/<%=name%>" {String}Optional

    The templated directory name of where each version's download and docs should be created. The default is "<%= version%>". This means that a 2.0.1 version name will be downloaded to a 2.0.1 folder. DocumentJS will then look for that version's documentjs.json and run that.

  5. sites {Object<String,siteConfig>}

    A map of site names and options that configure their behavior.

  6. siteDefaults {siteConfig}

    Default values for any sites configs.

Use

A docConfig is most commonly found in documentjs.json. It configures the behavior of DocumentJS. There are two main behaviors that docObject controls:

  • The retrieval of other projects or versions to be documented.
  • The documentation behavior of the current project.

A complex configuration, like the one used for producing CanJS.com, might looks like:

{
  versions: {
    "1.1.8" : "https://github.com/bitovi/canjs/tree/1.1-legacy",
    "2.1.4" : "https://github.com/bitovi/canjs/tree/v2.1.4",
    "2.2.0-pre" : "https://github.com/bitovi/canjs/tree/minor",
    "3.0.0-pre" : {
      "source": "https://github.com/bitovi/canjs/tree/major",
      "npmInstall" : true
    }
  },
  versionDest: "<%= version %>",
  defaultVersion: "2.1.4",
  defaultDest: ".",
  siteDefaults: {
    "templates" : "theme/templates"
  },
  sites: {
    pages: {
      pattern: "_pages/*.md",
      dest: "."
    }
  }
}

This configuration will download the listed versions into "./<%= version %>/canjs" except for 2.1.4, which be downloaded to "./canjs". Then each version's documentjs.json will be generated. Finally, all markdown files in _pages will be generated to ".".