elasticsearch-js/scripts/utils/generateDocs.js

/*
 * Licensed to Elasticsearch B.V. under one or more contributor
 * license agreements. See the NOTICE file distributed with
 * this work for additional information regarding copyright
 * ownership. Elasticsearch B.V. licenses this file to you 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.
 */

'use strict'

const dedent = require('dedent')

function generateDocs (common, spec) {
  var doc = dedent`
  [[api-reference]]
  == API Reference

  ////////

  This documentation is generated by running:
  node scripts/run.js --tag v7.0.0-beta

  ////////\n\n`
  doc += commonParameters(common)
  spec.forEach(s => {
    doc += '\n' + generateApiDoc(s)
  })
  return doc
}

function commonParameters (spec) {
  var doc = dedent`
  === Common parameters
  Parameters that are accepted by all API endpoints.

  link:{ref}/common-options.html[Reference]
  [cols=2*]
  |===\n`
  Object.keys(spec.params).forEach(key => {
    const name = isSnakeCased(key) && key !== camelify(key)
      ? '`' + key + '` or `' + camelify(key) + '`'
      : '`' + key + '`'

    doc += dedent`
    |${name}
    |${'`' + spec.params[key].type + '`'} - ${spec.params[key].description}`
    if (spec.params[key].default) {
      doc += ` +
    _Default:_ ${'`' + spec.params[key].default + '`'}`
    }
    doc += '\n\n'
  })

  doc += dedent`
  |===
  `
  return doc
}

function generateApiDoc (spec) {
  const name = Object.keys(spec)[0]
  const documentationUrl = fixLink(name, spec[name].documentation)
  const params = []
  // url params
  const urlParts = spec[name].url.parts
  if (urlParts) {
    Object.keys(urlParts).forEach(param => {
      params.push({
        name: param,
        type: getType(urlParts[param].type, urlParts[param].options),
        description: urlParts[param].description,
        default: urlParts[param].default
      })
    })
  }

  // query params
  const urlParams = spec[name].url.params
  if (urlParams) {
    Object.keys(urlParams).forEach(param => {
      params.push({
        name: param,
        type: getType(urlParams[param].type, urlParams[param].options),
        description: urlParams[param].description,
        default: urlParams[param].default
      })
    })
  }

  // body params
  const body = spec[name].body
  if (body) {
    params.push({
      name: 'body',
      type: 'object',
      description: body.description,
      default: body.default
    })
  }

  var doc = dedent`
  === ${camelify(name)}
  [source,js]
  ----
  client.${camelify(name)}([params] [, options] [, callback])
  ----\n`
  if (documentationUrl) {
    doc += `link:${documentationUrl}[Reference]\n`
  }

  if (params.length !== 0) {
    doc += dedent`[cols=2*]
    |===\n`
    doc += params.reduce((acc, val) => {
      const name = isSnakeCased(val.name) && val.name !== camelify(val.name)
        ? '`' + val.name + '` or `' + camelify(val.name) + '`'
        : '`' + val.name + '`'
      acc += dedent`
      |${name}
      |${'`' + val.type + '`'} - ${val.description}`
      if (val.default) {
        acc += ` +\n_Default:_ ${'`' + val.default + '`'}`
      }
      return acc + '\n\n'
    }, '')

    doc += dedent`
    |===
    `
  }
  doc += '\n'
  return doc
}

const LINK_OVERRIDES = {
  'license.delete': '{ref}/delete-license.html',
  'license.get': '{ref}/get-license.html',
  'license.get_basic_status': '{ref}/get-basic-status.html',
  'license.get_trial_status': '{ref}/get-trial-status.html',
  'license.post': '{ref}/update-license.html',
  'license.post_start_basic': '{ref}/start-basic.html',
  'license.post_start_trial': '{ref}/start-trial.html',
  'migration.deprecations': '{ref}/migration-api-deprecation.html',
  'monitoring.bulk': '{ref}/es-monitoring.html',
  'ingest.delete_pipeline': '{ref}/delete-pipeline-api.html',
  'ingest.get_pipeline': '{ref}/get-pipeline-api.html',
  'ingest.put_pipeline': '{ref}/put-pipeline-api.html',
  'ingest.simulate': '{ref}/simulate-pipeline-api.html',
  'ingest.processor_grok': '{ref}/grok-processor.html#grok-processor-rest-get'
}
// Fixes bad urls in the JSON spec
function fixLink (name, str) {
  /* In 6.x some API start with `xpack.` when in master they do not. We
   * can safely ignore that for link generation. */
  name = name.replace(/^xpack\./, '')
  const override = LINK_OVERRIDES[name]
  if (override) return override
  if (!str) return ''
  /* Replace references to the guide with the attribute {ref} because
   * the json files in the Elasticsearch repo are a bit of a mess. */
  str = str.replace(/^.+guide\/en\/elasticsearch\/reference\/[^/]+\/([^./]*\.html(?:#.+)?)$/, '{ref}/$1')
  str = str.replace(/frozen\.html/, 'freeze-index-api.html')
  str = str.replace(/ml-file-structure\.html/, 'ml-find-file-structure.html')
  str = str.replace(/security-api-get-user-privileges\.html/, 'security-api-get-privileges.html')

  return str
}

function getType (type, options) {
  switch (type) {
    case 'list':
      return 'string, string[]'
    case 'date':
    case 'time':
    case 'timeout':
      return 'string'
    case 'enum':
      return options.map(k => `'${k}'`).join(', ')
    case 'int':
    case 'double':
    case 'long':
      return 'number'
    default:
      return type
  }
}

function camelify (str) {
  return str[0] === '_'
    ? '_' + str.slice(1).replace(/_([a-z])/g, k => k[1].toUpperCase())
    : str.replace(/_([a-z])/g, k => k[1].toUpperCase())
}

function isSnakeCased (str) {
  return !!~str.indexOf('_')
}

module.exports = generateDocs