vuepress-plugin-autodoc

Vuepress Autodoc Plugin

Overview

VuePress plugin for automatic code documentation via JSDoc with an API similar to sphinx.ext.autodoc.

Installation

Install in Project

To use this library in a Vue project, add the package to your package dependencies via:

npm install --save-dev vuepress-plugin-autodoc

Or, with yarn:

yarn add -D vuepress-plugin-autodoc

Quickstart

Configuration

To use this in documentation for a project, follow the VuePress guidelines. Here is a quick example:

module.exports = {
  plugins: [ 'vuepress-plugin-autodoc' ]
}

Referencing Code

Once you've configured VuePress to use this plugin, you can automatically generate API documentation for code in your project using:

# API Section

## Full Documentation

/autodoc src/index.js


## Document Specific Objects

/autodoc src/index.js myFunction MyClass myConst

This will automatically render styled API documentation for code elements with JSDoc-compatible docstrings.

This type of dynamic auto-documentation allows developers to be clear in how their API is structured, providing context alongside their API documentation. For example, let's say we have a file in our project that looks like:

// contents of src/index.js

/**
* Generic number class
*/
export class Number {

 /**
  * Constructor for object.
  * @param {Number} input - Number to add.
  * @param {String} name - Name for number.
  */
  constructor(input) {
    this.number = input || 0;
    this.name = name;
  }

  /**
   * Return number from class.
   * @return {Number} The number value.
   */
   value() {
     return this.number;
   }

   /**
    * Add another number and return result.
    * @param {Number} other - Other number to add.
    * @return {Number} Other number to add.
    */
    increment(other) {
      return this.number + other;
    }
}

/**
 * Function for adding two numbers.
 * @param {Number} x - Left operand.
 * @param {Number} y - Right operand.
 */
export function add(x, y) {
  return x + y;
}


/**
 * Object with functions and data.
 */
const utils = {
  /**
   * Item in utils array.
   */
   item: false,
  /**
   * Echo value.
   *
   * @param {Number} value - Value to echo.
   */
   echo: value => console.log(value),
}

We can render pre-formatted code documentaton for specific items using the following markdown syntax:

// contents of docs/README.md

# API Documentation

Here is documentation for specific elements from our module:

/autodoc src/index.js add Number utils

And here are all of the documented elements:

/autodoc src/index.js

To show sidebar links for auto-documented items, place a header tag with the name of the item immediately before the /autodoc statement:

# Classes

## Number

/autodoc src/index.js Number

# Functions

## add

/autodoc src/index.js add

## subtract

/autodoc src/index.js subtract

Example

See a demo of the documentation here.