elv-ramdoc

This is a JSDoc template created by customizing the template used by Ramda's API documentation.

These are the major changes:

• Added 'Show private' checkbox to filter
• Added support for @curried tag
• Changed HTML templating engine from handlebars to pug
• Changed CSS templating engine from less to sass
• Updated bootstrap to version 5.1.3
• Enhanced filtering to also show/hide the detailed entries, not just the table of contents rows
• Removed 'Open in REPL' / 'Run it here' links, as well as some tag sections we did not need (e.g.aka)
• Made project name and GitHub links dynamic by retrieving info from package.json
• Added Eluvio logo (linking to https://eluv.io) and favicon

Install

$ npm install --save-dev @eluvio/elv-ramdoc

Prerequisites and conventions

The following are assumed by this template and this README:

• Your code is hosted on GitHub
• Your project's repo has version tags (e.g.v0.0.1)
• Your project's documentation is in top level directory docs
• Your project has GitHub Pages enabled
  • Make sure your account or organization has GitHub Pages enabled
  • Configure GitHub Pages for your project
    • Go to your project's Settings → Pages screen
    • Under Source, pick the branch and the folder (/docs)
• You have the following files at the top level of your repo:
  • README.md
  • .jsdoc.json (see below for sample)
  • package.json with the following attributes:
    • name
    • version
    • homepage set to the URL of your project's GitHub pages root
    • repository.url set to the URL of your project's GitHub repo

NOTE: You should put a link to the API documentation in your README.md file that connects to GitHub pages, e.g.:

## API Documentation

[https://eluv-io.github.io/elv-ramdoc/api.html](https://eluv-io.github.io/elv-ramdoc/api.html)

Example package.json fragment

Note that homepage is set to project GitHub Pages root, while repository.url points to the GitHub project page.

{
  "name": "@eluvio/elv-ramdoc",
  "version": "0.0.2",
  "homepage": "https://eluv-io.github.io/elv-ramdoc",
  "repository": {
    "type": "git",
    "url": "https://github.com/eluv-io/elv-ramdoc"
  }
}

Example .jsdoc.json file

Assumes the following:

• Your .js files are in src/
• Your documentation files are in docs/
• You want to include items that have @private specified

{
  "tags": {
    "allowUnknownTags": ["category","curried","sig"],
    "dictionaries": ["jsdoc"]
  },
  "source": {
    "include": ["src"],
    "includePattern": ".js$",
    "excludePattern": "(node_modules/|docs)"
  },
  "plugins": [
    "plugins/markdown"
  ],
  "opts": {
    "destination": "./docs/",
    "encoding": "utf8",
    "pedantic": true,
    "private": true,
    "recurse": true,
    "template": "node_modules/@eluvio/elv-ramdoc"
  }
}

Usage (node.js)

In your projects package.json file add a new script:

"script": {
  "generate-docs": "jsdoc --readme README.md --configure .jsdoc.json"
}

Running this task with npm run generate-docs will generate your documentation.

If you would like to print the data being processed, set environment variable ELV_RAMDOC_DEBUG:

"script": {
  "generate-docs-debug": "export ELV_RAMDOC_DEBUG=1; jsdoc --readme README.md --configure .jsdoc.json"
}

In order for the GitHub source code links to work properly, you should rebuild and commit the docs with the npm version lifecycle hook, so that the docs will be rebuilt immediately after version number is bumped in package.json:

"script": {
  "version": "npm run generate-docs && git add docs && git commit -m 'Update docs'"
}

API Documentation

https://eluv-io.github.io/elv-ramdoc/api.html

License

MIT