andstor / jsdoc-action

:book: :octocat:GitHub Action to build JSDoc documentation

Hi there, I'm André Storhaug 👋

/ˈɑːndɹe ˈstoˑɹhaːg/

I am a PhD student 🎓 at the Norwegian University of Science and Technology (NTNU), pursuing a Doctor of Philosophy (PhD) degree in Computer Science.

📫 How to reach me:

• Email: [email protected]

jsdoc-action's Issues

Willing to test

Hi,

i am interested in this project. Feel free to query me if you got your first version running.

GitHub Pages example gives code error

Getting an error when copy pasting the GitHub Pages example code:

Invalid Workflow File
every step must define a `uses` or `run` key

Seems that there is a typo in the example workflow code.

Need to remove the hyphen in - uses: actions/checkout@v2.
There should only be one per step.

Output folder created, but nothing shows up in the repo after workflow finishes

Hello, I set up a simple GitHub repo with a Javascript file that I'm using to test out your tool, and I'm having an issue with no output showing up in the repo afterward. I'm following the example you provided, omitting the deployment section

Unless I'm misunderstanding something, I'm assuming it will save the result in the repo with the output_dir given.

If I did misunderstand and its not intended to save the results to the GitHub repo itself, would you happen to know a way of saving it to master without needing to manually upload a saved artifact?

The Accessibility Menu

It does a lot of fun things

Template version pinning

Hi, is it possible to enable version pinning of a specific theme template?

Unable to find the source file or directory /home/runner/work/_actions/andstor/jsdoc-action/v1/app/js

My action file looks as follows, based on your example for github pages:

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: ./app
          output_dir: ./docs/test
          config_file: jsdoc.json
          template_name: docdash
          front_page: README.md

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

If executed it fails in the Build section, see the following log:

Run andstor/jsdoc-action@v1
  with:
    source_dir: ./app
    output_dir: ./docs/test
    config_file: jsdoc.json
    template_name: docdash
    front_page: README.md
    recurse: true
Installing JSDoc template: docdash
/usr/local/bin/npm install docdash --production
+ [email protected]
added 3 packages from 3 contributors and audited 882321 packages in 7.954s
found 0 vulnerabilities

📝 Generating documentation
/usr/local/bin/node /home/runner/work/_actions/andstor/jsdoc-action/v1/node_modules/jsdoc/jsdoc.js /home/runner/work/media-dupes/media-dupes/app -r -c /home/runner/work/media-dupes/media-dupes/jsdoc.json -t node_modules/docdash -R /home/runner/work/media-dupes/media-dupes/README.md -d /home/runner/work/media-dupes/media-dupes/docs/test
ERROR: Unable to find the source file or directory /home/runner/work/_actions/andstor/jsdoc-action/v1/app/js
ERROR: Unable to find the source file or directory /home/runner/work/_actions/andstor/jsdoc-action/v1/main.js
Parsing /home/runner/work/media-dupes/media-dupes/app/js/modules/crashReporter.js ...
Parsing /home/runner/work/media-dupes/media-dupes/app/js/modules/ffmpeg.js ...
Parsing /home/runner/work/media-dupes/media-dupes/app/js/modules/githubUrls.js ...
Parsing /home/runner/work/media-dupes/media-dupes/app/js/modules/sentry.js ...
Parsing /home/runner/work/media-dupes/media-dupes/app/js/modules/settings.js ...
Parsing /home/runner/work/media-dupes/media-dupes/app/js/modules/ui.js ...
Parsing /home/runner/work/media-dupes/media-dupes/app/js/modules/unhandled.js ...
Parsing /home/runner/work/media-dupes/media-dupes/app/js/modules/utils.js ...
Parsing /home/runner/work/media-dupes/media-dupes/app/js/modules/youtubeDl.js ...
Parsing /home/runner/work/media-dupes/media-dupes/app/js/renderer.js ...
Generating output files...
Finished running in 0.99 seconds.
##[error]The process '/usr/local/bin/node' failed with exit code 1

Any idea about this issue? Is that an error from me?

version missing critical updates

please publish an updated version with an updated version of jsdoc or selectable version thereof

fix javascript doc reported by jsdoc

Methods/Functions are mentioned several times

While i now have your action running i am starting to check the resulting output. At least for me it looks like my module functions are mentioned several times in the resulting html output.

Example output:
https://yafp.github.io/media-dupes/module-ffmpeg.html

Related js source file:
https://github.com/yafp/media-dupes/blob/master/app/js/modules/ffmpeg.js

Related jsdoc config file:
https://github.com/yafp/media-dupes/blob/master/jsdoc.json

Related action:
https://github.com/yafp/media-dupes/actions?query=workflow%3A%22GitHub+pages%22

This does not happens if i generate them manually.

Any idea what might cause this?

Error: Cannot find module 'escape-string-regexp'

Hi @andstor -- thanks much for the plugin! Wondering if you might be able to take a look at this config/error?

name: JSDoc

on: [pull_request]

jobs:
  install:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Build
        uses: andstor/[email protected]
        with:
          source_dir: ./src/modules
          output_dir: ./out
          template: minami
          front_page: README.md

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

📝 Generating documentation
/usr/local/bin/node /home/runner/work/_actions/andstor/jsdoc-action/v1.0.2/node_modules/jsdoc/jsdoc.js /home/runner/work/iron/iron/src/modules -r -R /home/runner/work/iron/iron/README.md -d /home/runner/work/iron/iron/out
internal/modules/cjs/loader.js:905
  throw err;
  ^

Error: Cannot find module 'escape-string-regexp'
Require stack:
- /home/runner/work/_actions/andstor/jsdoc-action/v1.0.2/node_modules/jsdoc/lib/jsdoc/name.js
- /home/runner/work/_actions/andstor/jsdoc-action/v1.0.2/node_modules/jsdoc/lib/jsdoc/app.js
- /home/runner/work/_actions/andstor/jsdoc-action/v1.0.2/node_modules/jsdoc/jsdoc.js
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:902:15)
    at Requizzle.requizzle (/home/runner/work/_actions/andstor/jsdoc-action/v1.0.2/node_modules/requizzle/lib/requizzle.js:84:29)
    at infectProxy (/home/runner/work/_actions/andstor/jsdoc-action/v1.0.2/node_modules/requizzle/lib/loader.js:79:31)
    at Module.targetModule.require (/home/runner/work/_actions/andstor/jsdoc-action/v1.0.2/node_modules/requizzle/lib/loader.js:97:44)
    at require (internal/modules/cjs/helpers.js:93:18)
    at Object.<anonymous> (/home/runner/work/_actions/andstor/jsdoc-action/v1.0.2/node_modules/jsdoc/lib/jsdoc/name.js:6:16)
    at Module._compile (internal/modules/cjs/loader.js:1085:14)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1114:10)
    at Module.load (internal/modules/cjs/loader.js:950:32)
    at Object.load (/home/runner/work/_actions/andstor/jsdoc-action/v1.0.2/node_modules/requizzle/lib/loader.js:105:18) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [
    '/home/runner/work/_actions/andstor/jsdoc-action/v1.0.2/node_modules/jsdoc/lib/jsdoc/name.js',
    '/home/runner/work/_actions/andstor/jsdoc-action/v1.0.2/node_modules/jsdoc/lib/jsdoc/app.js',
    '/home/runner/work/_actions/andstor/jsdoc-action/v1.0.2/node_modules/jsdoc/jsdoc.js'
  ]
}
Error: The process '/usr/local/bin/node' failed with exit code 1

The Accessibility Menu

New

Need help with running jsdoc-action with my local repo

Error: ENOENT: no such file or directory, open '/home/runner/work/_actions/andstor/jsdoc-action/v1/details./package.json

I'm getting this error in my github actions: https://github.com/lark-parser/Lark.js/runs/4422204241?check_suite_focus=true

This is the yml: https://github.com/lark-parser/Lark.js/blob/master/.github/workflows/jsdoc.yml

Worth noting that this exact same yml worked before, and I didn't change it.

Also, running jsdoc locally works for me.

How to use a github repo as template?

Hello,
I forked the minami repository. The package URL is now Androz2091/minami. It's successfully installed:

But, the package name is still "minami", not "Androz2091/minami". So the package is not found in the node_modules folder.

This problem concerns every template published on github, as the npm package name is AUTHOR/TEMPLATE_NAME. Maybe if the template_name includes a /, it would be possible to split on it and to keep the second string...

What's the best way to use a custom domain with GitHub Pages?

Hello,
I'm using your action for my repository. Here is my current workflow:

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: ./docs
          config_file: .jsdoc.json
          template_name: Androz2091/minami
          front_page: README.md

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

So as you can see, I'm building the docs with your action, and then deploying them with actions-gh-pages. The problem is that GitHub Pages doesn't use my custom domain name (if I add a CNAME to the gh-pages branch, it's overwritten each time). So, what is the best way to support a custom domain? Committing the CNAME file to my master branch and (I couldn't find how) tell to jsdoc to keep this file in the output directory? Or adding an option "cname: custom-domain.com" to your action, so your script adds a CNAME file with the domain name?
I don't know, if you could give me more information and what you think, thank you.

Using action with local repo

Hi,

I want to use jsdoc-action to generate a github page with my local repo. I have previously used the action with my other repo and I am really impressed with it.

.yml file: https://github.com/chinmay-kothari/bookbrainz-site/blob/master/.github/workflows/documentation.yml

conf.json: https://github.com/chinmay-kothari/bookbrainz-site/blob/master/conf.json

Can you provide any help on where I might be going wrong here? Thanks!