How to use documentation - 10 common examples

// This script generates a full documentation for the API.

const documentation = require('documentation')
// streamArray and vfs can be used because these are dependencies of documentation.
const streamArray = require('stream-array')
const vfs = require('vinyl-fs')

console.log(`Building API documentation. This can take a few moments ...`)
documentation.build([
  'source/main.js',
  'source/renderer/zettlr-renderer.js'
], {
  // config: 'documentation.yml',
  projectName: 'Zettlr',
  projectHomepage: 'https://www.zettlr.com'
})
  .then(comments => documentation.formats.html(comments, {}))
  .then(output => {
    streamArray(output).pipe(vfs.dest('resources/docs'))
    console.log('Done generating API documentation!')
  })

function buildChildDoc(inputPath, outputPath, actionMap, config) {
  return documentation.build(inputPath, {...INPUT_CONFIG, ...config})
    .then(res => {
      // res is an array of parsed comments with inferred properties
      // and more: everything you need to build documentation or
      // any other kind of code data.
      let processed = res;

      if (outputPath.includes('actions.md')) {
        // add action type and updater links to action
        processed = res.map(node => _appendActionTypesAndUpdatersToActions(node, actionMap));
      } else if (inputPath.some(p => p.includes('reducers'))) {
        // add action type and updater links to action
        processed = res.map(node => _appendActionToUpdaters(node, actionMap));
      }

      return documentation.formats.remark(processed, OUT_CONFIG)
    })

async function generate(app, sources, output) {
    let task = app.log(`generating API references... (${output})`, true);
    // start the `documentation` task.
    try {
        let builder = await documentation.build(sources, {});
        // format the result using markdown.
        let contents = await documentation.formats.md(builder);
        // write the final result.
        fs.ensureDirSync(path.dirname(output));
        fs.writeFileSync(output, contents);
        task();
        app.log(`${colors.bold(colors.green('documentation created.'))} ${colors.grey(`(${output.localPath})`)}`);
    } catch(err) {
        // ops.
        task();
        throw err;
    }
}

*/

const path = require('path'),
    documentation = require('documentation'),
    Promise = require('bluebird'),
    fs = Promise.promisifyAll(require('fs'));

/**
 * Cotains type definitions and where should their link point to
 *
 * @type       {Object}
 */
const paths = require('param-links');

// Build Documentation
documentation
    .build(['index.js'], {
        shallow: true,
        hljs: {
            highlightAuto: true,
            languages: ['js', 'json', 'sql', 'sh', 'bash']
        }
    })
    .then(res => {
        return documentation.formats.md(res, {
            paths,
            hljs: {
                highlightAuto: true,
                languages: ['js', 'json', 'sql', 'sh', 'bash']
            }
        });
    })

.then(res => {
      // res is an array of parsed comments with inferred properties
      // and more: everything you need to build documentation or
      // any other kind of code data.
      let processed = res;

      if (outputPath.includes('actions.md')) {
        // add action type and updater links to action
        processed = res.map(node => _appendActionTypesAndUpdatersToActions(node, actionMap));
      } else if (inputPath.some(p => p.includes('reducers'))) {
        // add action type and updater links to action
        processed = res.map(node => _appendActionToUpdaters(node, actionMap));
      }

      return documentation.formats.remark(processed, OUT_CONFIG)
    })
    .then(output => {

/* eslint-disable */
var fs = require('fs'),
  path = require('path'),
  File = require('vinyl'),
  vfs = require('vinyl-fs'),
  _ = require('lodash'),
  concat = require('concat-stream'),
  GithubSlugger = require('github-slugger'),
  createFormatters = require('documentation').util.createFormatters,
  LinkerStack = require('documentation').util.LinkerStack,
  hljs = require('highlight.js');

function isFunction(section) {
  return (
    section.kind === 'function' ||
    (section.kind === 'typedef' &&
      section.type.type === 'NameExpression' &&
      section.type.name === 'Function')
  );
}

module.exports = function(
  comments,
  config
) {
  var linkerStack = new LinkerStack(config).namespaceResolver(

/* eslint-disable import/no-extraneous-dependencies, prefer-destructuring,
no-mixed-operators, guard-for-in, no-buffer-constructor, no-restricted-syntax */

const fs = require('fs');
const path = require('path');
const write = require('vinyl-write');
const Vinyl = require('vinyl');
const _ = require('lodash');
const GithubSlugger = require('github-slugger');
const createFormatters = require('documentation').util.createFormatters;
const LinkerStack = require('documentation').util.LinkerStack;
const hljs = require('highlight.js');

function isFunction(section) {
  return section.kind === 'function' || section.kind === 'typedef' &&
    section.type.type === 'NameExpression' && section.type.name === 'Function';
}

module.exports = function (comments, config) {
  const linkerStack = new LinkerStack(config).namespaceResolver(comments, (namespace) => {
    const slugger = new GithubSlugger();
    return `#${slugger.slug(namespace)}`;
  });
  const formatters = createFormatters(linkerStack.link);

  // Add an Index

import React from 'react';
import GithubSlugger from 'github-slugger';
import createFormatters from 'documentation/src/output/util/formatters';
import LinkerStack from 'documentation/src/output/util/linker_stack';
import docs from '../components/api.json'; // eslint-disable-line import/no-unresolved
import ApiItem from '../components/api-item';
import Icon from '@mapbox/mr-ui/icon';

const linkerStack = new LinkerStack({})
    .namespaceResolver(docs, (namespace) => {
        const slugger = new GithubSlugger();
        return `#${slugger.slug(namespace)}`;
    });

const formatters = createFormatters(linkerStack.link);

class ApiItemMember extends React.Component {
    constructor(props) {
        super(props);
        this.state = {disclosed: false};
        this.hashChange = this.hashChange.bind(this);
    }

    href = m => `#${m.namespace.toLowerCase()}`

    render() {
        const member = this.props;
        return (
            <div>
                <div id="{member.namespace.toLowerCase()}" style="{{">
                <div></div></div></div>

import LinkerStack from 'documentation/src/output/util/linker_stack';
import GithubSlugger from 'github-slugger';
import {highlightJavascript} from '../components/prism_highlight.js';
import docs from '../components/api.json'; // eslint-disable-line import/no-unresolved
import ApiItemMember from './api-item-member';
import IconText from '@mapbox/mr-ui/icon-text';
import Feedback from '@mapbox/dr-ui/feedback';
import constants from '../constants';

const linkerStack = new LinkerStack({})
    .namespaceResolver(docs, (namespace) => {
        const slugger = new GithubSlugger();
        return `#${slugger.slug(namespace)}`;
    });

const formatters = createFormatters(linkerStack.link);

class ApiItem extends React.Component {

    constructor(props) {
        super(props);
        this.state = {
            userName: undefined
        };
    }

    componentDidMount() {
        MapboxPageShell.afterUserCheck(() => {
            this.setState({ userName: MapboxPageShell.getUser() ?
                MapboxPageShell.getUser().id :
                undefined});
        });

import {version} from '../../package.json';
import docs from '../components/api.json'; // eslint-disable-line import/no-unresolved
import GithubSlugger from 'github-slugger';
import createFormatters from 'documentation/src/output/util/formatters';
import LinkerStack from 'documentation/src/output/util/linker_stack';
import ApiItem from '../components/api-item';

const meta = {
    title: 'API Reference',
    description: 'The Mapbox GL JS API documentation to render interactive maps from vector tiles and Mapbox styles.',
    pathname: '/mapbox-gl-js/api/',
    contentType: 'API',
    lanaguage: ['JavaScript']
};

const linkerStack = new LinkerStack({})
    .namespaceResolver(docs, (namespace) => {
        const slugger = new GithubSlugger();
        return `#${slugger.slug(namespace)}`;
    });

const formatters = createFormatters(linkerStack.link);

function md(ast, inline) {
    if (inline && ast && ast.children.length && ast.children[0].type === 'paragraph') {
        ast = {
            type: 'root',
            children: ast.children[0].children.concat(ast.children.slice(1))
        };
    }
    return <span>;
}</span>