Getting Started

The configuration options documented here only contain add-on options for jsdoc. See the jsdoc configuration for the full list of configuration options. All of the jsdoc configuration works as described in the JSDoc configuration as it does in jsdocp. Only additions are made to the configuration opts.jsdocp (See Configuration for more details).

How It Works

At the core of jsdocp is a wrapper around jsdoc that provides all of the features listed in the README.

  1. The supplied configuration is sanitized and merged into a master configuration file (see Configuration)
  2. Previous npm published versions are captured via npm view versions and stored in the opts.destination directory as versions.json (see Documentation Versions)
  3. Parameter substitutions are resolved within the master configuration's opts (see Parameter Substitutions)
  4. The internal jsdocp templates are injected into the layout (the rest of the templates are supplied by the template of your choosing):
  • head: Placed in the head of every page that supplies the user-defined links/CSS sources, meta, etc.
  • nav: Placed as the first entry to every page's body that contains all of the navigation links to the npm module, CHANGELOG, source code, document version selection, etc.
  • foot: Placed as the last entry to every page's body that contains user-defined scripts
  1. The jsdoc command is ran using the internally processed master configuration file as input
  2. The CHANGELOG.md and parsed CHANGELOG.html are generated in the opts.destinaiton directory (generated/filtered via git log using the supplied rich set of configuration options)
  3. jsdocp markdown extensions are parsed on the tutorials (see the Parameter Substitutions section for more details)
  4. Publishing control is transferred to the template designated by opts.template

Setup (windows users can use git for windows)

  1. npm install -D <template>
    • Replace <template> with the desired template to use (see jsdoc templates)
  2. npm install -D jsdocp
    • Install jsdocp as a dev dependency
  3. mkdir -p jsdocp/static jsdocp/tutorial && touch jsdocp/jsdoc.conf
    • Create the directories that will be used by jsdocp
    • Add the desired static/tutorial files (e.g. CSS, scripts, images, tutorials, etc.)
  4. Add the desired jsdoc/jsdocp configuration options to the jsdocp/jsdoc.conf file. The example jsdocp configuration can be used as a guide.
    At minumum, ensure the follwing are set:
    • source - All the source files that should be included in the docs
    • opts.template - Set to a path to the actual jsdoc template being used. The template should be a module acceessible on npm and the path should be relative to the module that jsdoc is generating documentation for (e.g. ./node_modules/myCoolTemplateModuleName).
  5. Add the following:
    • your package.json...
    "scripts": {
    "jsdocp": "jsdocp ./jsdocp/jsdoc.json",
    "jsdocp-deploy": "jsdocp -D ./jsdocp/jsdoc.json"
}
  6. npm run jsdocp will generate the docs in the module's ./docs (unless overridden in the Configuration)

Deployment (assumes setup has been completed)

There are a few different ways that deployment can be performed based upon opts.jsdocp.deploy options. Deployment can occur locally or using a different git hosting service and running npm run jsdocp-deploy, but it will require some minor changes to conf.opts.jsdocp.deploy in the jsdoc.conf file outlined in the setup. However, we'll cover the most common use case where GitHub Pages and travis-ci are being used.

  1. If the gh-pages branch isn't already created/selected for GitHub Pages on https://github.com/<your_username>/<your_repo_name>/settings, the following script can be used to create the gh-pages branch. NOTE: Make sure to commit any changes to your currently checked out branch before proceeding to run the following script.
    git checkout --orphan gh-pages
git rm -rf .
touch README.md
git add README.md
git commit -m 'Initial gh-pages commit'
git push origin gh-pages
  2. Create a personal access token on GitHub.
  3. If you haven't already done so, go to travis-ci.com, setup an account and follow the instructions to enable/activate your repo. Copy the personal access token from GitHub in the previous step and paste it in a new Environment Variable called GITHUB_TOKEN on https://travis-ci.com/<your_username>/<your_repo_name>/settings.
  4. While your at it, you may also want to do the same thing for npm by creating an Access Token on https://www.npmjs.com/settings/<your_username>/tokens and copy/paste it in a new Environment Variable called NPM_TOKEN on https://travis-ci.com/<your_username>/<your_repo_name>/settings and put quotes around the value pasted: "my-npm-token-value" (we'll use this in our .travis.yml to deploy to npm).
  5. Create a .travis.yml in the root of your project using the .travis.yml below as a guide.
  6. npm version patch -m "Deploying %s" && git push origin <tag_name> - replacing patch with major, minor, etc. as needed (see npm-version)

Now everytime that a new version is tagged/pushed a new version of the npm package will be updated on https://www.npmjs.com/package/<your_package_name> and the docs will get updated on https://<your_username>.github.io/<your_repo_name> automatically! 

# .travis.yml
# When a tagged commit is pushed the documentation pages and npm module are published/deployed:
# npm version patch -m "%s Release"
language: node_js
node_js:
  - "lts/*"
branches:
  only:
    - master
    - "/v*/"
script:
# - printenv
  - "npm test"
# Using before_deploy will run before every deploy resulting in running multiple times when there is
# one or more deploy providers and will run regardless of the "on" directive used on the desired
# provider. Instead, a single script provider handles any pre-deployment executions.
#before_deploy:
#  - "npm run jsdocp"
deploy:
# Using the pages provider will wipe out previously deployed pages for prior versions. This makes it
# difficult to navigate version history and link to via documentation.
#  - provider: pages
#    skip-cleanup: true
#    github-token: $GITHUB_TOKEN  # Set in the settings page of your repository, as a secure variable
#    keep-history: true
#    target-branch: gh-pages
#    local-dir: docs
#    on:
#      tags: true # only on tagging commit
#      all_branches: true
  - provider: script
    skip_cleanup: true
    script: npm run jsdocp-deploy
    on:
      tags: true # only on tagging commit
      branch:
        - /v(\d+\.)?(\d+\.)?(\*|\d+)$/
  - provider: npm
    email: "ugate.public@gmail.com"
    api_key: $NPM_TOKEN  # Set in the settings page of your repository, as a secure variable
    on:
      tags: true # only on tagging commit
      branch:
        - /v(\d+\.)?(\d+\.)?(\*|\d+)$/

Configuration >>


1.3.0 (2021-08-20)

Full Changelog

Features: