diff --git a/.compodocrc b/.compodocrc new file mode 100644 index 00000000000..cd8b42152a6 --- /dev/null +++ b/.compodocrc @@ -0,0 +1,10 @@ +--- +tsconfig: ./tsconfig.json +output: ./docs +theme: material +hideGenerator: true +disablePrivate: true +disableProtected: true +disableInternal: true +disableCoverage: true +disableGraph: true diff --git a/README.md b/README.md index 2ec0bae4f5a..e0231f30e85 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ * [Installation](#installation) * [First example](#first-example) * [Samples](#samples) - * [Reference API](#reference-api) + * [API Reference](#api-reference) * [Authentication and authorization](#authentication-and-authorization) * [OAuth2 client](#oauth2-client) * [Using API keys](#using-api-keys) @@ -108,6 +108,9 @@ runSample().catch(console.error); ### Samples There are a lot of [samples](https://github.com/googleapis/google-api-nodejs-client/tree/master/samples) 🤗 If you're trying to figure out how to use an API ... look there first! If there's a sample you need missing, feel free to file an [issue][bugs]. +### API Reference +This library has a full set of [API Reference Documenation](https://apis-nodejs.firebaseapp.com/). This documentation is auto-generated, and the location may change. + ## Authentication and authorization The are three primary ways to authenticate to Google APIs. Some service support all authentication methods, other may only support one or two. diff --git a/package.json b/package.json index 729b8e3ec14..e37da98228c 100644 --- a/package.json +++ b/package.json @@ -25,7 +25,9 @@ "pretest": "npm run compile", "prepare": "npm run compile", "test": "nyc mocha build/test", - "docs": "echo no docs 👻", + "docs": "echo your docs are in another castle 🏰", + "pregenerate-docs": "npm run build-tools", + "generate-docs": "node build/src/generator/docs", "system-test": "mocha build/system-test", "samples-test": "cd samples && npm link ../ && pwd && npm test", "lint": "gts check && eslint 'samples/**/*.js'", @@ -53,6 +55,8 @@ "node": ">=6.0" }, "devDependencies": { + "@compodoc/compodoc": "^1.1.7", + "@types/execa": "^0.9.0", "@types/minimist": "^1.2.0", "@types/mkdirp": "^0.5.2", "@types/mocha": "^5.2.0", @@ -75,6 +79,7 @@ "eslint-config-prettier": "^3.0.1", "eslint-plugin-node": "^8.0.0", "eslint-plugin-prettier": "^3.0.0", + "execa": "^1.0.0", "gts": "^0.9.0", "hard-rejection": "^1.0.0", "intelli-espower-loader": "^1.0.1", diff --git a/src/generator/docs.ts b/src/generator/docs.ts new file mode 100644 index 00000000000..44525a8b437 --- /dev/null +++ b/src/generator/docs.ts @@ -0,0 +1,58 @@ +/** + * Copyright 2018 Google LLC. All Rights Reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import * as execa from 'execa'; +import * as fs from 'fs'; +import * as nunjucks from 'nunjucks'; +import * as Q from 'p-queue'; +import * as path from 'path'; +import {promisify} from 'util'; + +const readdir = promisify(fs.readdir); +const writeFile = promisify(fs.writeFile); +const srcPath = path.join(__dirname, '../../../src'); +const apiPath = path.join(srcPath, 'apis'); +const templatePath = path.join(srcPath, 'generator/templates/index.html.njk'); +const indexPath = path.join(__dirname, '../../../docs/index.html'); + +/** + * Iterate over each API directory, and use the `compodoc` tool to generate + * reference API documentation in the `docs` folder. This folder is ignored + * in git, so a publish must be done with `npm run publish-docs`. + * + * To use this, run `npm run generate-docs`. + */ +async function main() { + const children = await readdir(apiPath); + const dirs = children.filter(x => !x.endsWith('.ts')); + const contents = nunjucks.render(templatePath, {apis: dirs}); + await writeFile(indexPath, contents); + const q = new Q({concurrency: 10}); + console.log(`Generating docs for ${dirs.length} APIs...`); + let i = 0; + const promises = dirs.map(dir => { + return q + .add( + () => execa( + 'npx', ['compodoc', `src/apis/${dir}`, '-d', `./docs/${dir}`])) + .then(() => { + i++; + console.log(`[${i}/${dirs.length}] ${dir}`); + }); + }); + await Promise.all(promises); +} +main().catch(console.error); diff --git a/src/generator/templates/index.html.njk b/src/generator/templates/index.html.njk new file mode 100644 index 00000000000..8ec5b5546d8 --- /dev/null +++ b/src/generator/templates/index.html.njk @@ -0,0 +1,41 @@ + + + + + +
+ + Google API Node.js Client +
+ + +