There are a lot of complexities around making a multi-version documentation engine easy to use and configure. Here's my best attempt for a few use cases:
CanJS multi-version
- Be able to document and publish branches / tags, allowing us to have branch releases to experiment.
- Be able to work on (and watch) a local repo for quick verification.
- Use npm or bower for version number
- A slight miss-match between NPM / Tagged version and documentation (we sometimes improve/fix documentation after a release)
documentjs: {
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",
"2.2.0-dirty-checking" : "https://github.com/bitovi/canjs/tree/dirty-checking",
"3.0.0-pre" : "https://github.com/bitovi/canjs/tree/major"
},
// ideally what would be automagically picked by the oldest version without cruft
defaultVersion: "2.1.4",
sourceDest: __dirname+"/<%= version%>/can"
sites: {
api: {
src: ["*.md",''],
ignore: ["guides"],
dest: __dirname+"/{version}/api"
},
guides: {
src: ["guides/*.md"],
dest: __dirname+"/{version}/guides",
"static" : [""],
"templates" : [""]
},
site: {
// root tells it to look somewhere other than the version location
root: __dirname,
src: ["_pages/*.md"],
dest: __dirname+"/",
"static" : [""],
"templates" : [""]
}
}
}
To download every project and rebuild all the documentation, one would write:
However, it's VERY likely you don't want to do that over and over, and you have a version of canjs local. To document ONLY that local version:
grunt documentjs:../path/to/canjs/
If you need to give it a version:
grunt documentjs:../path/to/[email protected]
Finally, if you want to just build the API docs:
grunt documentjs:../path/to/[email protected]:api