Skip to content
You're viewing an older version of this GitHub Action. Do you want to see the latest version instead?
file-text

GitHub Action

JSDoc Action

v1.0.2

JSDoc Action

file-text

JSDoc Action

GitHub Action to build JSDoc documentation

Installation

Copy and paste the following snippet into your .yml file.

              

- name: JSDoc Action

uses: andstor/[email protected]

Learn more about this action in andstor/jsdoc-action

Choose a version

jsdoc-action

A GitHub Action to build JSDoc documentation

This is a GitHub Action to build your JavaScript documentation with JSDoc. JSDoc templates are supported. This action can easily be combied with other deployment actions, in order to publish the generated documentation to for example GitHub Pages.

The following example workflow step will generate documentation for all source files in the ./src directory and output the built files to the ./out directory.

- name: Build
  uses: andstor/jsdoc-action@v1
  with:
    source_dir: ./src
    output_dir: ./out

Supported platforms

The jsdoc-action is a JavaScript action and is supported on both Linux, MacOS and Windows.

OS (runs-on) ubuntu-latest macos-latest windows-latest
Support ✅️ ✅️ ✅️

Options ⚙️

The following input variables options can/must be configured:

Input variable Necessity Description Default
source_dir Required Source directory to build documentation from.
output_dir Optional Output folder for the generated documentation. ./out
recurse Optional Recurse into subdirectories when scanning for source files. true
config_file Optional The path to a JSDoc configuration file.
template_name Optional The name of a JSDoc template package to install. Will run a npm install template_name.
template_dir Optional The relative location of the template files directory within the template package.
front_page Optional The path to a Markdown file to be used as a the front page. Normally README.md.

Templates 💅

You can use JSDoc templates with this action.
Just set the template_name input variable to the name of the template you want to use. This needs to be template's package name.

If the template's template files is located somewhere else than the package's root, you need to specify this. Set the template_dir input variable to the location of the template folder (contains a publish.js file).

For example, to use the JSDoc DocStrap template, set the template_name to ink-docstrap and the template_dir to template.

JSDoc Configuration file 📄

To use a JSDoc configuration file located in your repository, you will need to specify the path to the file in the config_file input variable. Normally, if you use the actions/checkout, this will just resolve to conf.json or conf.js.

Examples

GitHub Pages 🚀

An example for deploying JSDoc generated documentationto GitHub Pages with actions-gh-pages.

This jsdoc-action workflow configuration uses the Minami JSDoc template and uses the root README.md file as frontpage.

name: GitHub pages

on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Build
        uses: andstor/jsdoc-action@v1
        with:
          source_dir: ./src
          output_dir: ./out
          config_file: conf.json
          template_name: minami
          front_page: README.md

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          publish_dir: ./out

License

Copyright © 2020 André Storhaug

The jsdoc-action GitHub action is licensed under the Apache License, Version 2.0.
See the LICENSE file for more information.