electron-docs-linter

Parse and validate Electron's API documentation.

Installation

npm install electron-docs-linter --save

CLI Usage

To lint the docs:

electron-docs-linter path/to/electron/docs

If errors are found, they are printed to STDERR and the process exits un-gracefully.

To lint the docs and save the generated JSON schema to a file:

electron-docs-linter docs/api --version=1.2.3 --outfile=api.json

Programmatic Usage

The module exports a function that parses markdown docs in a given directory, then returns a JSON representation of all the APIs.

const lint = require('electron-docs-linter')
const docPath = './test/fixtures/electron/docs/api'
const targetVersion = '1.2.3' // the soon-to-be-released version of electron

lint(docPath, targetVersion).then(function (apis) {
  // `apis` is an array of API objects. To find one:
  var win = apis.find(api => api.name === 'BrowserWindow')

  // The array also has a string key for each API name, so
  // you can access APIs like this too:
  win = apis.BrowserWindow

  win.events.length
  // => 25

  win.events[0]
  // {
  //   "name": "page-title-updated",
  //   "description": "Emitted when the document...",
  //   "returns": [
  //     {
  //       "name": "event",
  //       "type": "Event"
  //     }
  //   ]
  // }

  win.instanceMethods[20]
  // {
  //   name: 'setSize',
  //   signature: '(width, height[, animate])'
  // }
})

How It Works

The linter starts with a list of all the API names as seed data.

Each API's structure is inferred by parsing its raw markdown documentation from the electron repo. The electron-docs module abstracts away the challenges of fetching file contents in bulk.

Electron's API documentation adheres to Electron Coding Style and the Electron Styleguide, so its content can be programmatically parsed. To make the content easy to parse, the raw markdown is converted to HTML using marky-markdown-lite, which returns a cheerio DOM object that can be queried and traversed using familiar CSS selectors.

The result is an array of API objects. The following metadata is included for each API, where appropriate:

name
description
type (Class or Module)
process (main, renderer, or both)
methods
events
static methods (aka class methods)
instance events
instance methods
instance properties
website URL
GitHub repository URL

Related Things and Prior Art

TypeScript Definitions

A lot of people want an up-to-date TypeScript definition file for Electron.

https://github.com/MarshallOfSound/Electron-DefinitelyTyped (WIP)
electron/electron#4875
https://www.npmjs.com/package/@types/electron
https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/github-electron
https://github.com/RyanCavanaugh/dts-dom - A DOM library for generation TypeScript declaration (.d.ts) files
https://github.com/lbovet/typson - Converts TypeScript to JSON-schema
https://github.com/lbovet/docson - Documentation for your JSON types

Dependencies

cheerio: Tiny, fast, and elegant implementation of core jQuery designed specifically for the server
clean-deep: Remove falsy, empty or nullable values from objects
decamelize: Convert a camelized string into a lowercased one with a custom separator: unicornRainbow → unicorn_rainbow
dedent: An ES6 string tag that strips indentation from multi-line strings
electron-docs: Fetch Electron documentation as raw markdown strings
keyed-array: Recursively add named keys to arrays of objects
lodash.pick: The lodash method _.pick exported as a module.
lodash.sum: The lodash method _.sum exported as a module.
marky-markdown-lite: A version of marky-markdown that does less
minimist: parse argument options
ora: Elegant terminal spinner
path-exists: Check if a path exists
pify: Promisify a callback-style function
revalidator: A cross-browser / node.js validator powered by JSON Schema
semver: The semantic version parser used by npm.
to-markdown: HTML-to-Markdown converter

Dev Dependencies

chai: BDD/TDD assertion library for node.js and the browser. Test framework agnostic.
mocha: simple, flexible, fun test framework
rimraf: A deep deletion module for node (like rm -rf)
standard: JavaScript Standard Style

License

MIT

isabella232 / electron-docs-linter Goto Github PK