From a2361e08b8dbbc2be5f1f9c797cd26cd7a7a8138 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Fri, 7 Aug 2015 18:44:33 -0600 Subject: [PATCH 01/12] Flexible doc generation --- doc/config.json | 21 ------ doc/index.md | 40 ---------- doc/layouts/main.html | 9 +++ doc/partials/class.html | 9 +++ doc/partials/function.html | 2 + doc/partials/method.html | 2 + doc/partials/module.html | 25 +++++++ doc/src/api/index.html | 8 ++ doc/template/layout.tmpl | 40 ---------- package.json | 9 ++- tasks/build-docs.js | 146 +++++++++++++++++++++++++++++++++++++ 11 files changed, 209 insertions(+), 102 deletions(-) delete mode 100644 doc/config.json delete mode 100644 doc/index.md create mode 100644 doc/layouts/main.html create mode 100644 doc/partials/class.html create mode 100644 doc/partials/function.html create mode 100644 doc/partials/method.html create mode 100644 doc/partials/module.html create mode 100644 doc/src/api/index.html delete mode 100644 doc/template/layout.tmpl create mode 100644 tasks/build-docs.js diff --git a/doc/config.json b/doc/config.json deleted file mode 100644 index 31e6cc3..0000000 --- a/doc/config.json +++ /dev/null @@ -1,21 +0,0 @@ -{ - "source": { - "include": ["api"] - }, - "opts": { - "destination": "./build/doc", - "encoding": "utf8", - "readme": "./doc/index.md", - "recurse": true, - "template": "./node_modules/minami" - }, - "plugins": [ - "plugins/markdown" - ], - "templates": { - "default": { - "layoutFile": "./doc/template/layout.tmpl", - "outputSourceFiles": false - } - } -} diff --git a/doc/index.md b/doc/index.md deleted file mode 100644 index 74af878..0000000 --- a/doc/index.md +++ /dev/null @@ -1,40 +0,0 @@ -## planet-client - -A JavaScript client for [Planet's imagery API](https://www.planet.com/docs/). - -### Installation - -The `planet-client` requires Node >= 0.12. Install the `planet-client` package `npm` (which comes with [Node](https://nodejs.org/)). - - npm install planet-client - -### Using the Library - -The `planet-client` package can be used in a Node based project or in the browser with a CommonJS module loader (like [Browserify](http://browserify.org/) or [Webpack](http://webpack.github.io/)). - -The library requires a global [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) implementation. This comes with Node >= 0.12 and [modern browsers](http://caniuse.com/#search=promise). To use `planet-client` in an environment without `Promise`, you can [use a polyfill](https://www.google.com/search?q=promise+polyfill). - -With the above prerequisites, you can start using the `planet-client` package in your application: - -```js -var planet = require('planet-client'); - -// set up your API key for all future requests -planet.auth.setKey(process.env.PL_API_KEY); - -var lastWeek = new Date(Date.now() - (7 * 24 * 60 * 60 * 1000)); - -var query = { - 'acquired.gte': lastWeek.toISOString() -}; - -planet.scenes.search(query) - .then(function(page) { - console.log('Total count: ' + page.data.count + ' scenes since ' + lastWeek); - }) - .catch(function(err) { - console.error('Failed to fetch scenes:', err.message); - }); -``` - -See the list of modules to the left for details on what is exported by the library. diff --git a/doc/layouts/main.html b/doc/layouts/main.html new file mode 100644 index 0000000..6236995 --- /dev/null +++ b/doc/layouts/main.html @@ -0,0 +1,9 @@ + + + + {{ title }} + + + {{{ contents }}} + + diff --git a/doc/partials/class.html b/doc/partials/class.html new file mode 100644 index 0000000..4c6c921 --- /dev/null +++ b/doc/partials/class.html @@ -0,0 +1,9 @@ +{{ name }} +

{{ description }}

+{{#if methods}} + +{{/if}} diff --git a/doc/partials/function.html b/doc/partials/function.html new file mode 100644 index 0000000..d6787dc --- /dev/null +++ b/doc/partials/function.html @@ -0,0 +1,2 @@ +{{ name }} +

{{ description }}

diff --git a/doc/partials/method.html b/doc/partials/method.html new file mode 100644 index 0000000..d6787dc --- /dev/null +++ b/doc/partials/method.html @@ -0,0 +1,2 @@ +{{ name }} +

{{ description }}

diff --git a/doc/partials/module.html b/doc/partials/module.html new file mode 100644 index 0000000..28b4230 --- /dev/null +++ b/doc/partials/module.html @@ -0,0 +1,25 @@ +
+

{{ name }}

+

{{ description }}

+ + {{#if classes}} + Classes: + + {{/if}} + + {{#if functions}} + Functions: + + {{/if}} + +
+ +
diff --git a/doc/src/api/index.html b/doc/src/api/index.html new file mode 100644 index 0000000..4b40b9b --- /dev/null +++ b/doc/src/api/index.html @@ -0,0 +1,8 @@ +--- +layout: main.html +title: API Docs +--- + +{{#each modules}} + {{>module this}} +{{/each}} diff --git a/doc/template/layout.tmpl b/doc/template/layout.tmpl deleted file mode 100644 index d8b211f..0000000 --- a/doc/template/layout.tmpl +++ /dev/null @@ -1,40 +0,0 @@ - - - - - <?js= title ?> - Documentation - - - - - - - - - - - - - - - - - -
- -

- - - -
- - - - - diff --git a/package.json b/package.json index 18ce1e5..2d90c5f 100644 --- a/package.json +++ b/package.json @@ -18,7 +18,9 @@ "test-debug": "mocha --debug-brk --recursive test", "start": "watchy --watch bin,examples,api,cli,test -- npm test", "postpublish": "npm run publish-doc", - "doc": "jsdoc --configure doc/config.json", + "apidoc": "jsdoc --template jsdoc-json --destination build/api.json api", + "doc": "npm run apidoc && node --harmony-generators tasks/build-docs.js", + "start-doc": "watchy --watch doc,api,tasks -- npm run doc", "publish-doc": "npm run doc && gh-pages --dist build/doc" }, "bin": { @@ -30,7 +32,12 @@ "eslint": "^0.22.1", "eslint-config-planet": "^2.0.0", "gh-pages": "^0.3.1", + "handlebars": "^3.0.3", "jsdoc": "^3.3.2", + "jsdoc-json": "^2.0.0", + "metalsmith": "^2.0.1", + "metalsmith-in-place": "^1.3.1", + "metalsmith-layouts": "^1.3.0", "minami": "^1.1.0", "mocha": "^2.2.5", "nyc": "^3.1.0", diff --git a/tasks/build-docs.js b/tasks/build-docs.js new file mode 100644 index 0000000..006c99d --- /dev/null +++ b/tasks/build-docs.js @@ -0,0 +1,146 @@ +var Metalsmith = require('metalsmith'); +var layouts = require('metalsmith-layouts'); +var inPlace = require('metalsmith-in-place'); + +var pkg = require('../package.json'); +var api = require('../build/api.json'); + +function getNamed(name, array) { + var item; + for (var i = 0, ii = array.length; i < ii; ++i) { + if (array[i].name === name) { + item = array[i]; + break; + } + } + if (!item) { + item = {name: name}; + array.push(item); + } + return item; +} + +var MOD_RE = /^module:([\w-]+)~/; + +function getModuleName(longname) { + var match = longname.match(MOD_RE); + if (!match) { + throw new Error('Expected to parse a module name from ' + longname); + } + return match[1]; +} + +var CLASS_RE = /^module:[\w-]+~([A-Z]\w+)$/; + +function getClassName(memberof) { + var match = memberof.match(CLASS_RE); + if (!match) { + throw new Error('Expected to parse a class name from ' + memberof); + } + return match[1]; +} + +function getModule(longname, modules) { + var name = getModuleName(longname); + return getNamed(name, modules); +} + +function getClass(memberof, classes) { + var name = getClassName(memberof); + return getNamed(name, classes); +} + +function organizeDocs(docs) { + var modules = []; + for (var i = 0, ii = docs.length; i < ii; ++i) { + var doc = docs[i]; + var module; + switch (doc.kind) { + case 'module': + module = getNamed(doc.name, modules); + assign(module, doc); + break; + case 'class': + module = getModule(doc.longname, modules); + if (!module.classes) { + module.classes = []; + } + module.classes.push(doc); + break; + case 'function': + module = getModule(doc.longname, modules); + if (doc.scope === 'instance') { + if (!module.classes) { + module.classes = []; + } + var cls = getClass(doc.memberof, module.classes); + if (!cls.methods) { + cls.methods = []; + } + cls.methods.push(doc); + } else { + if (!module.functions) { + module.functions = []; + } + module.functions.push(doc); + } + break; + default: + //pass + } + } + return modules; +} + +function assign(target, source) { + for (var key in source) { + target[key] = source[key]; + } + return target; +} + +function main(callback) { + + var modules = organizeDocs(api.docs).filter(function(module) { + return module.access !== 'private'; + }).sort(function(a, b) { + return a.name < b.name ? -1 : 1; + }); + + var smith = new Metalsmith('.') + .source('doc/src') + .destination('build/doc') + .concurrency(25) + .metadata({ + version: pkg.version, + modules: modules + }) + .use(inPlace({ + engine: 'handlebars', + partials: 'doc/partials' + })) + .use(layouts({ + engine: 'handlebars', + directory: 'doc/layouts' + })) + .build(function(err) { + callback(err); + }); + + return smith; +} + +if (require.main === module) { + main(function(err) { + if (err) { + process.stderr.write( + 'Building docs failed. See the full trace below.\n\n' + + err.stack + '\n'); + process.exit(1); + } else { + process.exit(0); + } + }); +} + +module.exports = main; From 695c51c11a633a9c0b16065de9e2880cdb121444 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Fri, 7 Aug 2015 18:44:53 -0600 Subject: [PATCH 02/12] Document page and errors --- api/errors.js | 1 - api/page.js | 1 - 2 files changed, 2 deletions(-) diff --git a/api/errors.js b/api/errors.js index ce3d50e..99099ee 100644 --- a/api/errors.js +++ b/api/errors.js @@ -1,7 +1,6 @@ /** * Includes specific Error types generated by API requests. * @module errors - * @private */ /** diff --git a/api/page.js b/api/page.js index a7e60ea..1eeab7b 100644 --- a/api/page.js +++ b/api/page.js @@ -1,7 +1,6 @@ /** * Provides a utility for working with pages of search results. * @module page - * @private */ var url = require('url'); From 74a72a0d8b6a8248c0b35ff626083dc6e0da8da7 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Fri, 7 Aug 2015 23:30:26 -0600 Subject: [PATCH 03/12] Single page of docs --- api/auth-store.js | 2 +- api/auth.js | 2 +- api/errors.js | 19 ++++++++++++++----- api/mosaics.js | 2 +- api/page.js | 12 ++++++------ api/quads.js | 2 +- api/request.js | 2 +- api/scenes.js | 2 +- api/urls.js | 2 +- api/util.js | 2 +- api/workspaces.js | 2 +- doc/layouts/main.html | 17 +++++++++++++++++ doc/partials/class.html | 16 +++++++++++----- doc/partials/function.html | 4 ++-- doc/partials/method.html | 4 ++-- doc/partials/module.html | 23 ++++++++++------------- package.json | 1 + tasks/build-docs.js | 36 ++++++++++++++++++++++++++++++------ 18 files changed, 102 insertions(+), 48 deletions(-) diff --git a/api/auth-store.js b/api/auth-store.js index b60a1ff..3841939 100644 --- a/api/auth-store.js +++ b/api/auth-store.js @@ -1,6 +1,6 @@ /** * Memory store for API key and token. - * @module auth-store + * @module planet-client/api/auth-store * @private */ diff --git a/api/auth.js b/api/auth.js index e8c3045..1f2e3d7 100644 --- a/api/auth.js +++ b/api/auth.js @@ -1,6 +1,6 @@ /** * Provides methods for setting API authentication credentials. - * @module auth + * @module planet-client/api/auth */ var errors = require('./errors'); diff --git a/api/errors.js b/api/errors.js index 99099ee..706d4eb 100644 --- a/api/errors.js +++ b/api/errors.js @@ -1,6 +1,9 @@ /** - * Includes specific Error types generated by API requests. - * @module errors + * Includes specific Error types generated by API requests. When a request + * method returns a promise that is rejected, you can use `instanceof` to + * determine what type of error you have. + * + * @module planet-client/api/errors */ /** @@ -9,6 +12,7 @@ * @param {XMLHttpRequest} response The response. * @param {string} body Any parsed response body. * @constructor + * @ignore */ function ResponseError(message, response, body) { this.message = message; @@ -20,12 +24,13 @@ ResponseError.prototype = new Error(); ResponseError.prototype.name = 'ResponseError'; /** - * The request was bad (400). + * The request was bad (status `400`). * @param {string} message Error message. * @param {XMLHttpRequest} response The response. * @param {Object} body Any parsed response body (as JSON). * @extends {ResponseError} * @constructor + * @ignore */ function BadRequest(message, response, body) { ResponseError.apply(this, arguments); @@ -35,12 +40,13 @@ BadRequest.prototype = new ResponseError(); BadRequest.prototype.name = 'BadRequest'; /** - * The request requires user authentication (401). + * The request requires user authentication (status `401`). * @param {string} message Error message. * @param {XMLHttpRequest} response The response. * @param {Object} body Any parsed response body (as JSON). * @extends {ResponseError} * @constructor + * @ignore */ function Unauthorized(message, response, body) { ResponseError.apply(this, arguments); @@ -50,12 +56,13 @@ Unauthorized.prototype = new ResponseError(); Unauthorized.prototype.name = 'Unauthorized'; /** - * The client is forbidden from making the request (403). + * The client is forbidden from making the request (status `403`). * @param {string} message Error message. * @param {XMLHttpRequest} response The response. * @param {Object} body Any parsed response body (as JSON). * @extends {ResponseError} * @constructor + * @ignore */ function Forbidden(message, response, body) { ResponseError.apply(this, arguments); @@ -71,6 +78,7 @@ Forbidden.prototype.name = 'Forbidden'; * @param {string} body Any parsed response body. * @extends {ResponseError} * @constructor + * @ignore */ function UnexpectedResponse(message, response, body) { ResponseError.apply(this, arguments); @@ -83,6 +91,7 @@ UnexpectedResponse.prototype.name = 'UnexpectedResponse'; * An error generated when the request is aborted. * @param {string} message Error message. * @constructor + * @ignore */ function AbortedRequest(message) { this.message = message; diff --git a/api/mosaics.js b/api/mosaics.js index d733fb5..de4f2d7 100644 --- a/api/mosaics.js +++ b/api/mosaics.js @@ -1,6 +1,6 @@ /** * Provides methods for getting scene metadata. - * @module mosaics + * @module planet-client/api/mosaics */ var Page = require('./page'); diff --git a/api/page.js b/api/page.js index 1eeab7b..f06fb6d 100644 --- a/api/page.js +++ b/api/page.js @@ -1,6 +1,6 @@ /** * Provides a utility for working with pages of search results. - * @module page + * @module planet-client/api/page */ var url = require('url'); @@ -12,13 +12,14 @@ var url = require('url'); * @param {function(Object):Promise} factory Function that creates a promise of * new data given a query object. * @constructor + * @ignore */ function Page(data, factory) { var links = data.links; /** - * Get the previous page. If there is no previous page, `previous` will be - * `null`. + * Get the previous page. If there is no previous page, `prev` will be + * `null`. * @param {Object} options Any request options. * @return {Promise.} The previous page. * @method @@ -28,10 +29,9 @@ function Page(data, factory) { }; /** - * Get the next page. + * Get the next page. If there is no next page, `next` will be `null`. * @param {Object} options Any request options. - * @return {Promise.} The next page. If there is no next page, - * `next` will be `null`. + * @return {Promise.} The next page. * @method */ this.next = !links.next ? null : function(options) { diff --git a/api/quads.js b/api/quads.js index 518c1c6..985c5ac 100644 --- a/api/quads.js +++ b/api/quads.js @@ -1,6 +1,6 @@ /** * Provides methods for getting mosaic quad metadata. - * @module quads + * @module planet-client/api/quads */ var Page = require('./page'); diff --git a/api/request.js b/api/request.js index bb114ef..a55caa6 100644 --- a/api/request.js +++ b/api/request.js @@ -1,6 +1,6 @@ /** * Provides methods for issuing API requests. - * @module requests + * @module planet-client/api/request * @private */ diff --git a/api/scenes.js b/api/scenes.js index 7b11eb3..1aa20e4 100644 --- a/api/scenes.js +++ b/api/scenes.js @@ -1,6 +1,6 @@ /** * Provides methods getting scene metadata. - * @module scenes + * @module planet-client/api/scenes */ var Page = require('./page'); diff --git a/api/urls.js b/api/urls.js index 5872b33..37b6c18 100644 --- a/api/urls.js +++ b/api/urls.js @@ -1,6 +1,6 @@ /** * API URL utilities. - * @module urls + * @module planet-client/api/urls * @private */ diff --git a/api/util.js b/api/util.js index 665c85d..086525c 100644 --- a/api/util.js +++ b/api/util.js @@ -1,6 +1,6 @@ /** * General utilities. - * @module util + * @module planet-client/api/util * @private */ diff --git a/api/workspaces.js b/api/workspaces.js index 33a0859..7da1be7 100644 --- a/api/workspaces.js +++ b/api/workspaces.js @@ -1,6 +1,6 @@ /** * Provides methods for working with workspaces. - * @module workspaces + * @module planet-client/api/workspaces * @private */ diff --git a/doc/layouts/main.html b/doc/layouts/main.html index 6236995..4c6425a 100644 --- a/doc/layouts/main.html +++ b/doc/layouts/main.html @@ -2,6 +2,23 @@ {{ title }} + {{{ contents }}} diff --git a/doc/partials/class.html b/doc/partials/class.html index 4c6c921..ef67273 100644 --- a/doc/partials/class.html +++ b/doc/partials/class.html @@ -1,9 +1,15 @@ -{{ name }} -

{{ description }}

+

+ {{#if ignore}} + mod.{{name}} + {{else}} + var {{lower name}} = new mod.{{name}}() + {{/if}} +

+

{{md description}}

{{#if methods}} -
    {{#each methods}} -
  • {{>method this}}
    • +
    + {{>method this}} +
    {{/each}} -
{{/if}} diff --git a/doc/partials/function.html b/doc/partials/function.html index d6787dc..9efb1f1 100644 --- a/doc/partials/function.html +++ b/doc/partials/function.html @@ -1,2 +1,2 @@ -{{ name }} -

{{ description }}

+

mod.{{name}}({{listParams params}})

+

{{md description}}

diff --git a/doc/partials/method.html b/doc/partials/method.html index d6787dc..9dad0ff 100644 --- a/doc/partials/method.html +++ b/doc/partials/method.html @@ -1,2 +1,2 @@ -{{ name }} -

{{ description }}

+

{{instance memberof}}.{{name}}()

+

{{md description}}

diff --git a/doc/partials/module.html b/doc/partials/module.html index 28b4230..1d98d44 100644 --- a/doc/partials/module.html +++ b/doc/partials/module.html @@ -1,25 +1,22 @@ -
-

{{ name }}

-

{{ description }}

+
+

{{name}}

+

{{md description}}

+

var mod = require('{{name}}')

{{#if classes}} - Classes: -
    {{#each classes}} -
  • {{>class this}}
    • +
    + {{>class this}} +
    {{/each}} -
{{/if}} {{#if functions}} - Functions: -
    {{#each functions}} -
  • {{>function this}}
    • +
    + {{>function this}} +
    {{/each}} -
{{/if}} -
-
diff --git a/package.json b/package.json index 2d90c5f..c6ef3a9 100644 --- a/package.json +++ b/package.json @@ -35,6 +35,7 @@ "handlebars": "^3.0.3", "jsdoc": "^3.3.2", "jsdoc-json": "^2.0.0", + "marked": "^0.3.5", "metalsmith": "^2.0.1", "metalsmith-in-place": "^1.3.1", "metalsmith-layouts": "^1.3.0", diff --git a/tasks/build-docs.js b/tasks/build-docs.js index 006c99d..5bc62f1 100644 --- a/tasks/build-docs.js +++ b/tasks/build-docs.js @@ -1,6 +1,8 @@ var Metalsmith = require('metalsmith'); -var layouts = require('metalsmith-layouts'); +var handlebars = require('handlebars'); var inPlace = require('metalsmith-in-place'); +var layouts = require('metalsmith-layouts'); +var marked = require('marked'); var pkg = require('../package.json'); var api = require('../build/api.json'); @@ -20,20 +22,20 @@ function getNamed(name, array) { return item; } -var MOD_RE = /^module:([\w-]+)~/; +var MODULE_NAME_RE = /^module:([\w-\/]+)~/; function getModuleName(longname) { - var match = longname.match(MOD_RE); + var match = longname.match(MODULE_NAME_RE); if (!match) { throw new Error('Expected to parse a module name from ' + longname); } return match[1]; } -var CLASS_RE = /^module:[\w-]+~([A-Z]\w+)$/; +var CLASS_NAME_RE = /^module:[\w-\/]+~([A-Z]\w+)$/; function getClassName(memberof) { - var match = memberof.match(CLASS_RE); + var match = memberof.match(CLASS_NAME_RE); if (!match) { throw new Error('Expected to parse a class name from ' + memberof); } @@ -117,7 +119,29 @@ function main(callback) { }) .use(inPlace({ engine: 'handlebars', - partials: 'doc/partials' + partials: 'doc/partials', + helpers: { + instance: function(memberof) { + var className = getClassName(memberof); + return className.charAt(0).toLowerCase() + className.slice(1); + }, + listParams: function(params) { + if (!params) { + return ''; + } + return params.map(function(param) { + return param.name; + }).filter(function(name) { + return name.indexOf('.') === -1; + }).join(', '); + }, + lower: function(str) { + return str.charAt(0).toLowerCase() + str.slice(1); + }, + md: function(str) { + return new handlebars.SafeString(marked(str)); + } + } })) .use(layouts({ engine: 'handlebars', From ddacbeebddd93de1df492eb86f7b3b43efcc997e Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Sat, 8 Aug 2015 12:13:33 -0500 Subject: [PATCH 04/12] Add params and returns --- doc/layouts/main.html | 42 ++++++++++++++++++++++++++++++++++---- doc/partials/class.html | 14 +++++++------ doc/partials/function.html | 12 ++++++++++- doc/partials/method.html | 12 ++++++++++- doc/partials/module.html | 9 +++++--- doc/partials/params.html | 8 ++++++++ doc/partials/returns.html | 1 + doc/partials/type.html | 1 + tasks/build-docs.js | 3 +++ 9 files changed, 87 insertions(+), 15 deletions(-) create mode 100644 doc/partials/params.html create mode 100644 doc/partials/returns.html create mode 100644 doc/partials/type.html diff --git a/doc/layouts/main.html b/doc/layouts/main.html index 4c6425a..11db2d0 100644 --- a/doc/layouts/main.html +++ b/doc/layouts/main.html @@ -6,17 +6,51 @@ html, body { margin: 1em; padding; 0; - font-family: Tahoma, Geneva, sans-serif; - background: #FBFFE8; - color: #272727; + font-family: "Open Sans",sans-serif,"Helvetica Neue",Helvetica,Arial,sans-serif; + background: #FFF; + color: #666; + } + a { + color: #00a9e9; + text-decoration: none; + } + a:hover, + a:focus { + color: #00729d; + text-decoration: none; + } + hr { + border: 0; + height: 1px; + background: #eee; } code { font-family: "Lucida Console", Monaco, monospace; - font-size: smaller; + font-size: 0.9em; color: #171A48; } .module { margin-bottom: 3em; + border: 1px solid #eee; + padding: 0 2em; + } + .function, + .method, + .class { + margin-bottom: 2em; + } + .params { + padding: 0 30px; + list-style-type: circle; + } + .param { + margin-bottom: 0.5em; + } + .param .separator { + color: #666; + } + .param code.type { + color: #666; } diff --git a/doc/partials/class.html b/doc/partials/class.html index ef67273..3f288cc 100644 --- a/doc/partials/class.html +++ b/doc/partials/class.html @@ -1,9 +1,11 @@ -

- {{#if ignore}} - mod.{{name}} - {{else}} - var {{lower name}} = new mod.{{name}}() - {{/if}} +

+ + {{#if ignore}} + mod.{{name}} + {{else}} + var {{lower name}} = new mod.{{name}}() + {{/if}} +

{{md description}}

{{#if methods}} diff --git a/doc/partials/function.html b/doc/partials/function.html index 9efb1f1..545484c 100644 --- a/doc/partials/function.html +++ b/doc/partials/function.html @@ -1,2 +1,12 @@ -

mod.{{name}}({{listParams params}})

+

+ + mod.{{name}}({{listParams params}}) + +

{{md description}}

+{{#if params}} + {{>params this}} +{{/if}} +{{#if returns}} + {{>returns this}} +{{/if}} diff --git a/doc/partials/method.html b/doc/partials/method.html index 9dad0ff..d67b572 100644 --- a/doc/partials/method.html +++ b/doc/partials/method.html @@ -1,2 +1,12 @@ -

{{instance memberof}}.{{name}}()

+

+ + {{instance memberof}}.{{name}}({{listParams params}}) + +

{{md description}}

+{{#if params}} + {{>params this}} +{{/if}} +{{#if returns}} + {{>returns this}} +{{/if}} diff --git a/doc/partials/module.html b/doc/partials/module.html index 1d98d44..f8f7c7a 100644 --- a/doc/partials/module.html +++ b/doc/partials/module.html @@ -1,6 +1,9 @@ -
-

{{name}}

+
+

+ {{name}} +

{{md description}}

+

var mod = require('{{name}}')

{{#if classes}} @@ -19,4 +22,4 @@

var mod = require('{{name}}')

{{/each}} {{/if}} -
+ diff --git a/doc/partials/params.html b/doc/partials/params.html new file mode 100644 index 0000000..cc2f406 --- /dev/null +++ b/doc/partials/params.html @@ -0,0 +1,8 @@ +
    + {{#each params}} +
  • + {{name}} : + {{>type this}} - {{description}} +
    • + {{/each}} +
diff --git a/doc/partials/returns.html b/doc/partials/returns.html new file mode 100644 index 0000000..7832ac7 --- /dev/null +++ b/doc/partials/returns.html @@ -0,0 +1 @@ +{{>type returns.[0]}} - {{returns.[0].description}} diff --git a/doc/partials/type.html b/doc/partials/type.html new file mode 100644 index 0000000..b24f10f --- /dev/null +++ b/doc/partials/type.html @@ -0,0 +1 @@ +{{join type.names "|"}} diff --git a/tasks/build-docs.js b/tasks/build-docs.js index 5bc62f1..80edb70 100644 --- a/tasks/build-docs.js +++ b/tasks/build-docs.js @@ -125,6 +125,9 @@ function main(callback) { var className = getClassName(memberof); return className.charAt(0).toLowerCase() + className.slice(1); }, + join: function(array, sep) { + return array.join(sep); + }, listParams: function(params) { if (!params) { return ''; From 8e735e68d44ab4e96664a99a610ef843864b45d4 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Sat, 8 Aug 2015 12:35:18 -0500 Subject: [PATCH 05/12] Add a toc --- doc/layouts/main.html | 30 ++++++++++++++++++++++++++++++ doc/partials/toc.html | 15 +++++++++++++++ doc/src/api/index.html | 12 ++++++++---- 3 files changed, 53 insertions(+), 4 deletions(-) create mode 100644 doc/partials/toc.html diff --git a/doc/layouts/main.html b/doc/layouts/main.html index 11db2d0..c167d78 100644 --- a/doc/layouts/main.html +++ b/doc/layouts/main.html @@ -29,6 +29,18 @@ font-size: 0.9em; color: #171A48; } + #sidebar { + position: fixed; + top: 0; + bottom: 0; + overflow: scroll; + width: 200px; + padding: 2em 2em 0 0; + box-sizing: border-box; + } + #content { + margin-left: 200px; + } .module { margin-bottom: 3em; border: 1px solid #eee; @@ -52,6 +64,24 @@ .param code.type { color: #666; } + .toc { + font-size: 0.8em; + } + .toc .module { + margin: 1em 0 0; + border: 0; + padding: 0; + } + .toc .classes, + .toc .functions { + margin: 0.5em 0; + list-style-type: circle; + padding: 0 20px; + } + .toc .function, + .toc .class { + margin: 0; + } diff --git a/doc/partials/toc.html b/doc/partials/toc.html new file mode 100644 index 0000000..adbd82b --- /dev/null +++ b/doc/partials/toc.html @@ -0,0 +1,15 @@ +
+{{#each modules}} +
{{name}}
+
    + {{#each classes}} +
  • {{name}}
    • + {{/each}} +
+
    + {{#each functions}} +
  • {{name}}
    • + {{/each}} +
+{{/each}} +
diff --git a/doc/src/api/index.html b/doc/src/api/index.html index 4b40b9b..67ab5d0 100644 --- a/doc/src/api/index.html +++ b/doc/src/api/index.html @@ -2,7 +2,11 @@ layout: main.html title: API Docs --- - -{{#each modules}} - {{>module this}} -{{/each}} + +
+ {{#each modules}} + {{>module this}} + {{/each}} +
From dff911f9e5a98982f5ffed8b4d50ba8c24fcf987 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Sat, 8 Aug 2015 14:38:40 -0500 Subject: [PATCH 06/12] Link types --- api/mosaics.js | 4 ++-- api/page.js | 4 ++-- api/quads.js | 4 ++-- api/scenes.js | 4 ++-- cli/find-mosaics.js | 3 ++- cli/find-quads.js | 3 ++- cli/find-scenes.js | 3 ++- doc/partials/type.html | 4 +++- tasks/build-docs.js | 29 ++++++++++++++++++++++++++--- 9 files changed, 43 insertions(+), 15 deletions(-) diff --git a/api/mosaics.js b/api/mosaics.js index de4f2d7..d7a7bfb 100644 --- a/api/mosaics.js +++ b/api/mosaics.js @@ -41,8 +41,8 @@ function get(id, options) { * resources in the response. True by default. * @param {function(function())} options.terminator A function that is called * with a function that can be called back to terminate the request. - * @return {Promise.} A promise that resolves to a page of mosaic - * metadata or is rejected with any error. + * @return {Promise.} A promise that + * resolves to a page of mosaic metadata or is rejected with any error. */ function search(query, options) { options = options || {}; diff --git a/api/page.js b/api/page.js index f06fb6d..45ced28 100644 --- a/api/page.js +++ b/api/page.js @@ -21,7 +21,7 @@ function Page(data, factory) { * Get the previous page. If there is no previous page, `prev` will be * `null`. * @param {Object} options Any request options. - * @return {Promise.} The previous page. + * @return {Promise.} The previous page. * @method */ this.prev = !links.prev ? null : function(options) { @@ -31,7 +31,7 @@ function Page(data, factory) { /** * Get the next page. If there is no next page, `next` will be `null`. * @param {Object} options Any request options. - * @return {Promise.} The next page. + * @return {Promise.} The next page. * @method */ this.next = !links.next ? null : function(options) { diff --git a/api/quads.js b/api/quads.js index 985c5ac..0be9e88 100644 --- a/api/quads.js +++ b/api/quads.js @@ -43,8 +43,8 @@ function get(mosaicId, quadId, options) { * resources in the response. True by default. * @param {function(function())} options.terminator A function that is called * with a function that can be called back to terminate the request. - * @return {Promise.} A promise that resolves to a page of quad - * metadata or is rejected with any error. + * @return {Promise.} A promise that + * resolves to a page of quad metadata or is rejected with any error. */ function search(mosaicId, query, options) { options = options || {}; diff --git a/api/scenes.js b/api/scenes.js index 1aa20e4..cb013d5 100644 --- a/api/scenes.js +++ b/api/scenes.js @@ -49,8 +49,8 @@ function get(scene, options) { * resources in the response. True by default. * @param {function(function())} options.terminator A function that is called * with a function that can be called back to terminate the request. - * @return {Promise.} A promise that resolves to a page of scene - * metadata or is rejected with any error. + * @return {Promise.} A promise that + * resolves to a page of scene metadata or is rejected with any error. */ function search(query, options) { options = options || {}; diff --git a/cli/find-mosaics.js b/cli/find-mosaics.js index d21905e..916c157 100644 --- a/cli/find-mosaics.js +++ b/cli/find-mosaics.js @@ -2,7 +2,8 @@ var mosaics = require('../api/mosaics'); /** * Recursively fetch all pages until the limit is reached. - * @param {Promise.} promise A promise that resolves to a page of mosaics. + * @param {Promise.} promise A promise that + * resolves to a page of mosaics. * @param {Array} list An array of mosaic metadata. * @param {number} limit The limit. * @return {Promise.} An array that resolves to an array of mosaics. diff --git a/cli/find-quads.js b/cli/find-quads.js index 36417d6..aa1129f 100644 --- a/cli/find-quads.js +++ b/cli/find-quads.js @@ -44,7 +44,8 @@ function resolveQuery(opts) { /** * Recursively fetch all pages until the limit is reached. - * @param {Promise.} promise A promise that resolves to a page of quads. + * @param {Promise.} promise A promise that + * resolves to a page of quads. * @param {Array} features An array of quad metadata. * @param {number} limit The limit. * @return {Promise.} An array that resolves to an array of quads. diff --git a/cli/find-scenes.js b/cli/find-scenes.js index 759ee18..2fc6180 100644 --- a/cli/find-scenes.js +++ b/cli/find-scenes.js @@ -133,7 +133,8 @@ function resolveQuery(opts) { /** * Recursively fetch all pages until the limit is reached. - * @param {Promise.} promise A promise that resolves to a page of scenes. + * @param {Promise.} promise A promise that + * resolves to a page of scenes. * @param {Array} features An array of scene metadata. * @param {number} limit The limit. * @return {Promise.} An array that resolves to an array of scenes. diff --git a/doc/partials/type.html b/doc/partials/type.html index b24f10f..a03dbf2 100644 --- a/doc/partials/type.html +++ b/doc/partials/type.html @@ -1 +1,3 @@ -{{join type.names "|"}} + + {{#each type.names}}{{#if @index}}|{{/if}}{{linkType this}}{{/each}} + diff --git a/tasks/build-docs.js b/tasks/build-docs.js index 80edb70..57f80e9 100644 --- a/tasks/build-docs.js +++ b/tasks/build-docs.js @@ -125,9 +125,6 @@ function main(callback) { var className = getClassName(memberof); return className.charAt(0).toLowerCase() + className.slice(1); }, - join: function(array, sep) { - return array.join(sep); - }, listParams: function(params) { if (!params) { return ''; @@ -138,6 +135,32 @@ function main(callback) { return name.indexOf('.') === -1; }).join(', '); }, + linkType: function(type) { + var openIndex = type.lastIndexOf('<'); + var closeIndex = type.indexOf('>'); + var match, link; + if (openIndex >= 0 && closeIndex > openIndex) { + match = type.slice(openIndex + 1, closeIndex).match( + CLASS_NAME_RE); + if (match) { + link = new handlebars.SafeString( + type.slice(0, openIndex + 1).replace('<', '<') + + '' + match[1] + '' + + type.slice(closeIndex).replace('>', '>')); + } else { + link = type; + } + } else { + match = type.match(CLASS_NAME_RE); + if (match) { + link = new handlebars.SafeString( + ' {{name}} : - {{>type this}} - {{description}} + {{>type this}} - {{md description}} {{/each}} diff --git a/doc/partials/returns.html b/doc/partials/returns.html index 7832ac7..ebdc547 100644 --- a/doc/partials/returns.html +++ b/doc/partials/returns.html @@ -1 +1 @@ -{{>type returns.[0]}} - {{returns.[0].description}} +{{>type returns.[0]}} - {{md returns.[0].description}} From 511100923a6b763e3b36fac8d202ee3e72e2f044 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Sat, 8 Aug 2015 15:09:20 -0500 Subject: [PATCH 08/12] Pull name out of code context --- doc/layouts/main.html | 4 ++-- doc/partials/class.html | 4 ++-- doc/partials/function.html | 4 +++- doc/partials/method.html | 4 +++- doc/partials/module.html | 2 +- doc/partials/toc.html | 18 +++++++++++++++--- 6 files changed, 26 insertions(+), 10 deletions(-) diff --git a/doc/layouts/main.html b/doc/layouts/main.html index b5173de..79309a6 100644 --- a/doc/layouts/main.html +++ b/doc/layouts/main.html @@ -29,8 +29,8 @@ font-size: 0.9em; color: #444; } - a code { - color: inherit; + a code .name { + color: #005575; } #sidebar { position: fixed; diff --git a/doc/partials/class.html b/doc/partials/class.html index 3f288cc..890f53b 100644 --- a/doc/partials/class.html +++ b/doc/partials/class.html @@ -1,9 +1,9 @@

{{#if ignore}} - mod.{{name}} + mod.{{name}} {{else}} - var {{lower name}} = new mod.{{name}}() + var {{lower name}} = new mod.{{name}}() {{/if}}

diff --git a/doc/partials/function.html b/doc/partials/function.html index 545484c..71f17d4 100644 --- a/doc/partials/function.html +++ b/doc/partials/function.html @@ -1,6 +1,8 @@

- mod.{{name}}({{listParams params}}) + + mod.{{name}}({{listParams params}}) +

{{md description}}

diff --git a/doc/partials/method.html b/doc/partials/method.html index d67b572..84ad023 100644 --- a/doc/partials/method.html +++ b/doc/partials/method.html @@ -1,6 +1,8 @@

- {{instance memberof}}.{{name}}({{listParams params}}) + + {{instance memberof}}.{{name}}({{listParams params}}) +

{{md description}}

diff --git a/doc/partials/module.html b/doc/partials/module.html index f8f7c7a..a1e9138 100644 --- a/doc/partials/module.html +++ b/doc/partials/module.html @@ -1,6 +1,6 @@

- {{name}} + {{name}}

{{md description}}

diff --git a/doc/partials/toc.html b/doc/partials/toc.html index adbd82b..15abb6f 100644 --- a/doc/partials/toc.html +++ b/doc/partials/toc.html @@ -1,14 +1,26 @@
{{#each modules}} -
{{name}}
+
+ + {{name}} + +
{{/each}} From 53ec7a1321870839a03357c61306e1701e408a34 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Sun, 9 Aug 2015 13:56:59 -0500 Subject: [PATCH 09/12] TOC for all --- doc/layouts/main.html | 25 +++++++++++------ doc/partials/module.html | 2 +- doc/partials/toc.html | 60 ++++++++++++++++++++++------------------ doc/src/api/index.html | 10 +++---- doc/src/cli/index.html | 48 ++++++++++++++++++++++++++++++++ doc/src/index.html | 58 ++++++++++++++++++++++++++++++++++++++ 6 files changed, 162 insertions(+), 41 deletions(-) create mode 100644 doc/src/cli/index.html create mode 100644 doc/src/index.html diff --git a/doc/layouts/main.html b/doc/layouts/main.html index 79309a6..c9b4fbd 100644 --- a/doc/layouts/main.html +++ b/doc/layouts/main.html @@ -41,14 +41,29 @@ padding: 2em 2em 0 0; box-sizing: border-box; } + #sidebar h1 { + margin-top: 0.5em; + font-size: 1.5em + } + #sidebar h2 { + margin-top: 1em; + font-size: 1.2em + } + #sidebar ul { + margin: 0.5em 0; + list-style-type: circle; + padding: 0 20px; + } #content { margin-left: 200px; } - .module { - margin-bottom: 3em; + section.separated { border: 1px solid #eee; padding: 0 2em; } + .module { + margin-bottom: 3em; + } .function, .method, .class { @@ -81,12 +96,6 @@ border: 0; padding: 0; } - .toc .classes, - .toc .functions { - margin: 0.5em 0; - list-style-type: circle; - padding: 0 20px; - } .toc .function, .toc .class { margin: 0; diff --git a/doc/partials/module.html b/doc/partials/module.html index a1e9138..b2a3c85 100644 --- a/doc/partials/module.html +++ b/doc/partials/module.html @@ -1,4 +1,4 @@ -
+

{{name}}

diff --git a/doc/partials/toc.html b/doc/partials/toc.html index 15abb6f..1ee273c 100644 --- a/doc/partials/toc.html +++ b/doc/partials/toc.html @@ -1,27 +1,33 @@ -
-{{#each modules}} -
- - {{name}} - -
- - -{{/each}} -
+
+

Planet Client

+
+

API Modules

+ {{#if api}} + {{#each modules}} +
+ + {{name}} + +
+ + + {{/each}} + {{/if}} +

CLI Usage

+
diff --git a/doc/src/api/index.html b/doc/src/api/index.html index 67ab5d0..68c1514 100644 --- a/doc/src/api/index.html +++ b/doc/src/api/index.html @@ -2,11 +2,11 @@ layout: main.html title: API Docs --- - -
+ +
{{#each modules}} {{>module this}} {{/each}} -
+
diff --git a/doc/src/cli/index.html b/doc/src/cli/index.html new file mode 100644 index 0000000..0d7d2e3 --- /dev/null +++ b/doc/src/cli/index.html @@ -0,0 +1,48 @@ +--- +layout: main.html +title: CLI Docs +--- + + +
+ +

Using the CLI

+ +

+ The planet-client package provides a planet executable. This can be installed globally (npm install --global planet-client), or if you install it locally, you can add the executable to your path (export PATH=path/to/node_modules/.bin:$PATH). +

+ +

+ The general syntax for the planet executable is planet [options]. To see a list of commands, run the following: +

+ + 
planet --help
+ +

+ You can get help for a specific command by adding --help to the command name (e.g. planet find-scenes --help). +

+ +

+ To take advantage of command line completion with the planet executable, you can run the following in bash: +

+ + 
eval "$(planet completion)"
+ +

+ To enable this every time you start a new shell, you can append the output of planet completion to your .bashrc: +

+ + 
planet completion >> ~/.bashrc
+ +

+ The CLI will be fully documented when it is a bit more stable. For now, you can get a preview of what's available with this video: +

+ + + + + +
diff --git a/doc/src/index.html b/doc/src/index.html new file mode 100644 index 0000000..9f6dd18 --- /dev/null +++ b/doc/src/index.html @@ -0,0 +1,58 @@ +--- +layout: main.html +title: Planet Client +--- + + + +
+

planet-client

+ +

+ A JavaScript client for Planet's imagery API. +

+ +

Installation

+ +

+ Install the planet-client package with npm (which comes with Node). +

+ + 
npm install planet-client
+ +

+ The planet-client package provides a library for use in your application and a planet executable for command line use. See details on both below. +

+ +

Using the Library

+ +

+ The planet-client package can be used in a Node based project or in the browser with a CommonJS module loader (like Browserify or Webpack). +

+ +

+ The library requires a global Promise implementation. This comes with Node >= 0.12 and modern browsers. To use planet-client in an environment without Promise, you can use a polyfill. +

+ +

+ With the above prerequisites, you can start using the planet-client package in your application. See the client API documentation for details on using the library. +

+ +

Using the CLI

+ +

+ The planet-client package provides a planet executable. This can be installed globally (npm install --global planet-client), or if you install it locally, you can add the executable to your path (export PATH=$PATH:path/to/node_modules/.bin). +

+ +

+ The general syntax for the planet executable is planet [options]. To see a list of commands, run the following: +

+ + 
planet --help
+ +

+ See the CLI docs for more details on using the planet command. +

+
From ac4283fb98b75be2ce25915fc27468edef50bb52 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Sun, 9 Aug 2015 14:42:44 -0500 Subject: [PATCH 10/12] Document members --- api/auth.js | 13 ++++++++----- api/errors.js | 36 +++++++++++++++++++++++++++++------- doc/layouts/main.html | 8 ++++++-- doc/partials/class.html | 7 +++++++ doc/partials/member.html | 9 +++++++++ doc/partials/params.html | 1 + doc/partials/returns.html | 1 + tasks/build-docs.js | 15 ++++++++++++--- 8 files changed, 73 insertions(+), 17 deletions(-) create mode 100644 doc/partials/member.html diff --git a/api/auth.js b/api/auth.js index 1f2e3d7..3990a8b 100644 --- a/api/auth.js +++ b/api/auth.js @@ -1,5 +1,5 @@ /** - * Provides methods for setting API authentication credentials. + * Provides methods for authenticating with a Planet API account. * @module planet-client/api/auth */ @@ -9,9 +9,10 @@ var store = require('./auth-store'); var urls = require('./urls'); /** - * Submit credentials for authentication. - * @param {string} email Email. - * @param {string} password Password. + * Submit credentials for authentication. Upon successful authentication, a + * token representing the user will be stored for subsequent API requests. + * @param {string} email The email associated with a Planet account. + * @param {string} password The password for a Planet account. * @return {Promise} A promise that resolves on successful login and is rejected * otherwise. */ @@ -47,7 +48,9 @@ function logout() { } /** - * Set an API key to be used for subsequent requests. + * Set an API key to be used for subsequent requests. This is an alternative + * to submitting credentials with the [`login`](#module:planet-client/api/auth~login) + * method. The stored key will be used for subsequent API requests. * @param {string} key An API key. */ function setKey(key) { diff --git a/api/errors.js b/api/errors.js index 706d4eb..91a1655 100644 --- a/api/errors.js +++ b/api/errors.js @@ -1,5 +1,5 @@ /** - * Includes specific Error types generated by API requests. When a request + * Includes specific `Error` types generated by API requests. When a request * method returns a promise that is rejected, you can use `instanceof` to * determine what type of error you have. * @@ -7,7 +7,7 @@ */ /** - * An error based on a server response. + * The base class for all response errors. * @param {string} message Error message. * @param {XMLHttpRequest} response The response. * @param {string} body Any parsed response body. @@ -15,10 +15,32 @@ * @ignore */ function ResponseError(message, response, body) { + + /** + * A message providing details about the error. + * @type {string} + */ this.message = message; + + /** + * The server response. + * @type {IncomingMessage} + */ this.response = response; + + /** + * Any parsed response body. For "expected" errors, this will be an object + * representing the JSON response body. + * @type {Object} + */ this.body = body; + + /** + * The stack trace for the error. + * @type {string} + */ this.stack = (new Error()).stack; + } ResponseError.prototype = new Error(); ResponseError.prototype.name = 'ResponseError'; @@ -28,7 +50,7 @@ ResponseError.prototype.name = 'ResponseError'; * @param {string} message Error message. * @param {XMLHttpRequest} response The response. * @param {Object} body Any parsed response body (as JSON). - * @extends {ResponseError} + * @extends {module:planet-client/api/errors~ResponseError} * @constructor * @ignore */ @@ -44,7 +66,7 @@ BadRequest.prototype.name = 'BadRequest'; * @param {string} message Error message. * @param {XMLHttpRequest} response The response. * @param {Object} body Any parsed response body (as JSON). - * @extends {ResponseError} + * @extends {module:planet-client/api/errors~ResponseError} * @constructor * @ignore */ @@ -60,7 +82,7 @@ Unauthorized.prototype.name = 'Unauthorized'; * @param {string} message Error message. * @param {XMLHttpRequest} response The response. * @param {Object} body Any parsed response body (as JSON). - * @extends {ResponseError} + * @extends {module:planet-client/api/errors~ResponseError} * @constructor * @ignore */ @@ -76,7 +98,7 @@ Forbidden.prototype.name = 'Forbidden'; * @param {string} message Error message. * @param {XMLHttpRequest} response The response. * @param {string} body Any parsed response body. - * @extends {ResponseError} + * @extends {module:planet-client/api/errors~ResponseError} * @constructor * @ignore */ @@ -88,7 +110,7 @@ UnexpectedResponse.prototype = new ResponseError(); UnexpectedResponse.prototype.name = 'UnexpectedResponse'; /** - * An error generated when the request is aborted. + * An error generated when the request is terminated. * @param {string} message Error message. * @constructor * @ignore diff --git a/doc/layouts/main.html b/doc/layouts/main.html index c9b4fbd..ba6c780 100644 --- a/doc/layouts/main.html +++ b/doc/layouts/main.html @@ -11,7 +11,7 @@ color: #666; } a { - color: #005575; + color: #00a9e9; text-decoration: none; } a:hover, @@ -30,7 +30,11 @@ color: #444; } a code .name { - color: #005575; + color: #00a9e9; + } + a:hover code .name, + a:focus code .name { + color: #00729d; } #sidebar { position: fixed; diff --git a/doc/partials/class.html b/doc/partials/class.html index 890f53b..1e5403f 100644 --- a/doc/partials/class.html +++ b/doc/partials/class.html @@ -15,3 +15,10 @@

{{/each}} {{/if}} +{{#if members}} + {{#each members}} +
+ {{>member this}} +
+ {{/each}} +{{/if}} diff --git a/doc/partials/member.html b/doc/partials/member.html new file mode 100644 index 0000000..934f1bb --- /dev/null +++ b/doc/partials/member.html @@ -0,0 +1,9 @@ +

+ + + {{instance memberof}}.{{name}} + + + : {{>type this}} +

+

{{md description}}

diff --git a/doc/partials/params.html b/doc/partials/params.html index 0664e73..bf61f78 100644 --- a/doc/partials/params.html +++ b/doc/partials/params.html @@ -1,3 +1,4 @@ +

Arguments

    {{#each params}}
  • diff --git a/doc/partials/returns.html b/doc/partials/returns.html index ebdc547..c9e03ce 100644 --- a/doc/partials/returns.html +++ b/doc/partials/returns.html @@ -1 +1,2 @@ +

    Returns

    {{>type returns.[0]}} - {{md returns.[0].description}} diff --git a/tasks/build-docs.js b/tasks/build-docs.js index 57f80e9..f02acc3 100644 --- a/tasks/build-docs.js +++ b/tasks/build-docs.js @@ -56,7 +56,7 @@ function organizeDocs(docs) { var modules = []; for (var i = 0, ii = docs.length; i < ii; ++i) { var doc = docs[i]; - var module; + var module, cls; switch (doc.kind) { case 'module': module = getNamed(doc.name, modules); @@ -67,7 +67,16 @@ function organizeDocs(docs) { if (!module.classes) { module.classes = []; } - module.classes.push(doc); + cls = getClass(doc.longname, module.classes); + assign(cls, doc); + break; + case 'member': + module = getModule(doc.longname, modules); + cls = getClass(doc.memberof, module.classes); + if (!cls.members) { + cls.members = []; + } + cls.members.push(doc); break; case 'function': module = getModule(doc.longname, modules); @@ -75,7 +84,7 @@ function organizeDocs(docs) { if (!module.classes) { module.classes = []; } - var cls = getClass(doc.memberof, module.classes); + cls = getClass(doc.memberof, module.classes); if (!cls.methods) { cls.methods = []; } From 6852224889d3947cd75498934ad3be5ad391f762 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Sun, 9 Aug 2015 21:23:17 -0400 Subject: [PATCH 11/12] Pre style and consistent sections --- doc/layouts/main.html | 6 ++++-- doc/src/api/index.html | 10 ++++++++-- doc/src/cli/index.html | 2 +- 3 files changed, 13 insertions(+), 5 deletions(-) diff --git a/doc/layouts/main.html b/doc/layouts/main.html index ba6c780..c719772 100644 --- a/doc/layouts/main.html +++ b/doc/layouts/main.html @@ -24,6 +24,10 @@ height: 1px; background: #eee; } + pre { + background: #eee; + padding: 1em; + } code { font-family: "Lucida Console", Monaco, monospace; font-size: 0.9em; @@ -64,8 +68,6 @@ section.separated { border: 1px solid #eee; padding: 0 2em; - } - .module { margin-bottom: 3em; } .function, diff --git a/doc/src/api/index.html b/doc/src/api/index.html index 68c1514..e37e9ea 100644 --- a/doc/src/api/index.html +++ b/doc/src/api/index.html @@ -5,8 +5,14 @@ -
    +
    +
    +

    API Modules

    +

    + The planet-client package is organized as a collection of modules that roughly follow the structure of the HTTP API. The API provides access to individual scenes from a variety of providers and mosaics of those scenes. +

    +
    {{#each modules}} {{>module this}} {{/each}} -
    + diff --git a/doc/src/cli/index.html b/doc/src/cli/index.html index 0d7d2e3..e9f5fa2 100644 --- a/doc/src/cli/index.html +++ b/doc/src/cli/index.html @@ -8,7 +8,7 @@
    -

    Using the CLI

    +

    CLI Usage

    The planet-client package provides a planet executable. This can be installed globally (npm install --global planet-client), or if you install it locally, you can add the executable to your path (export PATH=path/to/node_modules/.bin:$PATH). From 135b25a46b1996454eeadda5e6ad2b15196ca431 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Sun, 9 Aug 2015 21:30:44 -0400 Subject: [PATCH 12/12] Return style --- doc/layouts/main.html | 6 +++++- doc/partials/returns.html | 4 +++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/doc/layouts/main.html b/doc/layouts/main.html index c719772..df9a415 100644 --- a/doc/layouts/main.html +++ b/doc/layouts/main.html @@ -31,7 +31,7 @@ code { font-family: "Lucida Console", Monaco, monospace; font-size: 0.9em; - color: #444; + color: #666; } a code .name { color: #00a9e9; @@ -91,6 +91,10 @@ .param p { display: inline; } + .returns { + padding: 0 30px; + list-style-type: circle; + } .returns p { display: inline; } diff --git a/doc/partials/returns.html b/doc/partials/returns.html index c9e03ce..80eee1d 100644 --- a/doc/partials/returns.html +++ b/doc/partials/returns.html @@ -1,2 +1,4 @@

    Returns

    -{{>type returns.[0]}} - {{md returns.[0].description}} +
      +
    • {{>type returns.[0]}} - {{md returns.[0].description}}
      • +