GitHub Action
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
recurse: true
output_dir: ./out
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 | ✅️ | ✅️ | ✅️ |
The following input variables options can/must be configured:
Input variable | Necessity | Description | Default |
---|---|---|---|
source_dir |
Optional | 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. | false |
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 . |
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
.
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
.
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
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.