okidoc

Tool to document your code easy and flexible

Installation

Install using the npm package manager:

$ npm install okidoc --save-dev

This installs package and put two commands in your ./node_modules/.bin path:

  • okidoc-md - generate human-readable documentation md files using source code with JSDoc and public method markers
  • okidoc-site - run and build documentation site based on md files and site config

You can use these commands in your npm scripts:

"scripts": {
  "documentation": "okidoc-md ./docs.yml ./docs",
  "documentation:gitadd": "npm run documentation && git add ./docs",
  "documentation:site": "okidoc-site develop ./site.yml",
  "documentation:site:build": "npm run documentation && okidoc-site build ./site.yml",
  "precommit": "npm run documentation:gitadd"
}

NOTE: if you don't need to generate markdown files or don't need a site, install only module you need

$ npm install okidoc-md --save-dev
$ # OR
$ npm install okidoc-site --save-dev

Generate documentation

Define what to document

Add @doc TAG_NAME tag to JSDoc of class or function

/**
 * My Super UI
 * @doc UI
 */
class MySuperUI {
  /**
   * show UI
   * @example
   * mySuperUI.show();
   */
  show() {}
}

/**
 * Subscribe on event
 * @param eventName - name of event
 * @param fn - event listener fn
 * @doc Events
 */
function subscribe(eventName: string, fn: Function) {}

Configure

Add yaml config (default config path is ./docs.yml):

# Get files using `entry` or/and `glob` (could be `.js` or `.ts` files),
# find api methods by `@doc UI` tag in JSDoc and generate markdown to `partial/ui.md` file.
- path: partial/ui.md
  title: UI API Methods
  # [optional] if provided, only `entry` file dependencies will be parsed
  entry: src/index.ts
  # [optional] required if `entry` not provided
  glob: src/**/*.ts
  # tag name have to match `@doc UI` in JSDoc
  tag: UI

- path: partial/events.md
  title: Events API
  glob: src/**/*.ts
  tag: Events

NOTE: With entry option, all dependency file source will be parsed for doc. Not only imported/exported part.

Execute

Run okidoc-md script

$ okidoc-md ./docs.yml ./docs

It will generates docs markdown using configuration from ./docs.yml and put them to ./docs directory

NOTE: ./docs.yml and ./docs are default values for configPath and outputDir arguments and can be omitted. Run okidoc-md --help for help.

To extract api methods with custom rule use visitor prop in docs.yml

Define markdown files

You can combine auto generated markdown files with manually created. Markdown should be written in gfm format.

Each markdown file can be annotated with YAML front matter. Here is a basic example:

---
title: 'okidoc'
layout: simple
include:
  - ./partial/api.md
---
# My super API

After this line content from `api.md` will be included.

Supported properties:

OPTIONVALUE
titleThe title for the page in <title> tag.
layoutOptionally define or override the layout to use. Available layouts: two-column - default layout, code examples are shown on right side.. simple - one column layout.
includeList of markdown files that will be included after content in the current markdown file.

Build documentation site

Site logic is based on gatsby.

Instead of default gatsby directory src/pages, use your docs path (example):

.
├── site.yml
├── /docs/                      # Site markdown files
│   ├── /index.md               # [required] site index page
│   ├── /other-markdown-file.md
│   └── ...                     # Other markdown files
└── ...

IMPORTANT: For site index page use index.md file (example). It is required file in your documentation directory. Other pages are available by file name without .md extension.

Only md files are served by okidoc-site.

Configure

To configure your site, use yaml config (default config path is ./site.yml):

# Markdown files path
# put index.md with content for site index page
docsPath: ./docs

# [optional] path for site build. Default path is `./site`
distPath: ./sitedist

config:
  # [optional] site metadata (https://www.gatsbyjs.org/docs/gatsby-config/#sitemetadata)
  siteMetadata:
    title: YOUR_DOCUMENTATION_SITE_TITLE
    description: YOUR_DOCUMENTATION_SITE_DESCRIPTION
    keywords: YOUR_DOCUMENTATION_SITE_KEYWORDS
  # [optional] path prefix
  pathPrefix: /my-awesome-lib
  # [optional] algolia apiKey and indexName for docsearch (https://www.algolia.com/ref/docsearch). If empty, search will be hidden
  algoliaApiKey: YOUR_ALGOLIA_API_KEY
  algoliaIndexName: YOUR_ALGOLIA_INDEX_NAME
  # [optional] Link to your github repository
  githubLink: YOUR_GITHUB_REPOSITORY

# [optional] react components inside markdown
mdComponents:
  path: ./docs/playground-components.js

# [optional] navigation config. Use if you need more than one page in navigation block
navigation:
  - path: /config
    title: Configuration
  - path: /methods
    title: Methods

Add navigation

navigation config

Add react components

react components inside markdown

Develop/Build

Run okidoc-site script

$ okidoc-site develop ./site.yml

Site will start a hot-reloading development environment accessible at localhost:8000

$ okidoc-site build ./site.yml

Will perform an optimized production build for your site generating static HTML and per-route JavaScript code bundles.

Read gatsby docs for more information

Deploy

If you use github for your repository, the easiest way to deploy site is to use gh-pages library:

"scripts": {
  "documentation:site:build": "npm run documentation && okidoc-site build ./site.yml",
  "documentation:site:deploy": "npm run documentation:site:build && gh-pages -d site",
}

For more deploy options read gatsby docs