Today we’re announcing some improvements to Electron’s documentation. Every new release now includes a JSON file that describes all of Electron’s public APIs in detail. We created this file to enable developers to use Electron’s API documentation in interesting new ways.
Each API is an object with properties like name, description, type, etc.
Classes such as BrowserWindow
and Menu
have additional properties describing
their instance methods, instance properties, instance events, etc.
Here’s an excerpt from the schema that describes the BrowserWindow
class:
{
name: 'BrowserWindow',
description: 'Create and control browser windows.',
process: {
main: true,
renderer: false
},
type: 'Class',
instanceName: 'win',
slug: 'browser-window',
websiteUrl: 'http://electron.atom.io/docs/api/browser-window',
repoUrl: 'https://github.com/electron/electron/blob/v1.4.0/docs/api/browser-window.md',
staticMethods: [...],
instanceMethods: [...],
instanceProperties: [...],
instanceEvents: [...]
}
And here’s an example of a method description, in this case the
apis.BrowserWindow.instanceMethods.setMaximumSize
instance method:
{
name: 'setMaximumSize',
signature: '(width, height)',
description: 'Sets the maximum size of window to width and height.',
parameters: [{
name: 'width',
type: 'Integer'
}, {
name: 'height',
type: 'Integer'
}]
}
To make it easy for developers to use this structured data in their projects, we’ve created electron-docs-api, a small npm package that is published automatically whenever there’s a new Electron release.
npm install electron-api-docs --save
For instant gratification, try out the module in your Node.js REPL:
npm i -g trymodule && trymodule electron-api-docs=apis
Electron’s API documentation adheres to Electron Coding Style and the Electron Styleguide, so its content can be programmatically parsed.
The electron-docs-linter
is a new development dependency of the electron/electron
repository.
It is a command-line tool that lints all the markdown files and enforces the
rules of the styleguide. If errors are found, they are listed and the release
process is halted. If the API docs are valid, the electron-json.api
file
is created and
uploaded to GitHub
as part of the Electron release.
Earlier this year, Electron’s codebase was updated to use the
standard
linter for all JavaScript. Standard’s
README sums up the reasoning behind this choice:
Adopting standard style means ranking the importance of code clarity and community conventions higher than personal style. This might not make sense for 100% of projects and development cultures, however open source can be a hostile place for newbies. Setting up clear, automated contributor expectations makes a project healthier.
We also recently created standard-markdown to verify that all the JavaScript code snippets in our documentation are valid and consistent with the style in the codebase itself.
Together these tools help us use continuous integration (CI) to automatically find errors in pull requests. This reduces the burden placed on humans doing code review, and gives us more confidence about the accuracy of our documentation.
Electron’s documentation is constantly improving, and we have our awesome open-source community to thank for it. As of this writing, nearly 300 people have contributed to the docs.
We’re excited to see what people do with this new structured data. Possible uses include:
Have feedback on this post? Let @ElectronJS know on Twitter.
Need help or found a bug? Contact us.