GitHub

Okidoc logo

okidoc

A flexible tool to document your code easily

Installation

Install using the npm package manager:

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

This installs the package and puts 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 the site config

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

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"
}

Generate documentation

Define what to document

Add @doc TAG_NAME JSDoc tags to your classes or functions

/**
 * 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 a 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 searching for `@doc UI` JSDoc tags and generate markdown into a `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` is not provided
  glob: src/**/*.ts
  # tag name has to match `@doc UI` in JSDoc
  tag: UI

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

NOTE: With the entry option specified, all source code of the dependency file will be parsed, not just the imported/exported part.

Execute

Run the okidoc-md script.

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

This will generate the docs markdown using configuration from ./docs.yml and put them into ./docs directory.

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

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

Define markdown files

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

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

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

After this line the contents of `api.md` will be included.

Supported properties:

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

Build the documentation site

Site logic is based on gatsby.

Instead of the default gatsby directory src/pages, make sure to 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: Use index.md file for the site index page (example). It's a required file in your documentation directory. Other pages are available by file name without the .md extension.

Only md files are served by okidoc-site.

Configure

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

# Path for markdown files
# add index.md with content for the site index page
docsPath: ./docs

# [optional] path for the site build. Default 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 this if you need more than one page in the 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 the okidoc-site script

$ okidoc-site develop ./site.yml

This will launch a hot-reloading development environment accessible at localhost:8000

$ okidoc-site build ./site.yml

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

Read on gatsby docs for more information

Deploy

If you use GitHub to host your repository, the easiest way to deploy your site is to use the 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 the gatsby docs