1"use strict";(self.webpackChunkelectronjs=self.webpackChunkelectronjs||[]).push([["19783"],{92855(e,n,t){t.r(n),t.d(n,{assets:()=>c,contentTitle:()=>i,default:()=>h,frontMatter:()=>a,metadata:()=>s,toc:()=>d});var s=t(47709),r=t(74848),o=t(28453);let a={title:"Electron's API Docs as Structured Data",date:new Date("2016-09-27T00:00:00.000Z"),authors:"zeke",slug:"api-docs-json-schema",tags:["website"]},i,c={authorsImageUrls:[void 0]},d=[{value:"Schema overview",id:"schema-overview",level:2},{value:"Using the new data",id:"using-the-new-data",level:2},{value:"How the data is collected",id:"how-the-data-is-collected",level:2},{value:"Standard Javascript and Standard Markdown",id:"standard-javascript-and-standard-markdown",level:2},{value:"A community effort",id:"a-community-effort",level:3}];function l(e){let n={a:"a",blockquote:"blockquote",code:"code",h2:"h2",h3:"h3",hr:"hr",li:"li",p:"p",pre:"pre",ul:"ul",...(0,o.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsxs)(n.p,{children:["Today we're announcing some improvements to Electron's documentation. Every new\nrelease now includes a\n",(0,r.jsx)(n.a,{href:"https://github.com/electron/electron/releases/download/v1.4.1/electron-api.json",children:"JSON file"}),"\nthat describes all of Electron's public APIs in detail. We created this file to\nenable developers to use Electron's API documentation in interesting new ways."]}),"\n",(0,r.jsx)(n.hr,{}),"\n",(0,r.jsx)(n.h2,{id:"schema-overview",children:"Schema overview"}),"\n",(0,r.jsxs)(n.p,{children:["Each API is an object with properties like name, description, type, etc.\nClasses such as ",(0,r.jsx)(n.code,{children:"BrowserWindow"})," and ",(0,r.jsx)(n.code,{children:"Menu"})," have additional properties describing\ntheir instance methods, instance properties, instance events, etc."]}),"\n",(0,r.jsxs)(n.p,{children:["Here's an excerpt from the schema that describes the ",(0,r.jsx)(n.code,{children:"BrowserWindow"})," class:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-js",children:"{\n name: 'BrowserWindow',\n description: 'Create and control browser windows.',\n process: {\n main: true,\n renderer: false\n },\n type: 'Class',\n instanceName: 'win',\n slug: 'browser-window',\n websiteUrl: 'https://electronjs.org/docs/api/browser-window',\n repoUrl: 'https://github.com/electron/electron/blob/v1.4.0/docs/api/browser-window.md',\n staticMethods: [...],\n instanceMethods: [...],\n instanceProperties: [...],\n instanceEvents: [...]\n}\n"})}),"\n",(0,r.jsxs)(n.p,{children:["And here's an example of a method description, in this case the\n",(0,r.jsx)(n.code,{children:"apis.BrowserWindow.instanceMethods.setMaximumSize"})," instance method:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-js",children:"{\n name: 'setMaximumSize',\n signature: '(width, height)',\n description: 'Sets the maximum size of window to width and height.',\n parameters: [{\n name: 'width',\n type: 'Integer'\n }, {\n name: 'height',\n type: 'Integer'\n }]\n}\n"})}),"\n",(0,r.jsx)(n.h2,{id:"using-the-new-data",children:"Using the new data"}),"\n",(0,r.jsxs)(n.p,{children:["To make it easy for developers to use this structured data in their projects,\nwe've created ",(0,r.jsx)(n.a,{href:"https://www.npmjs.com/package/electron-api-docs",children:"electron-docs-api"}),", a small\nnpm package that is published automatically whenever there's a new Electron\nrelease."]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-sh",children:"npm install electron-api-docs --save\n"})}),"\n",(0,r.jsx)(n.p,{children:"For instant gratification, try out the module in your Node.js REPL:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-sh",children:"npm i -g trymodule && trymodule electron-api-docs=apis\n"})}),"\n",(0,r.jsx)(n.h2,{id:"how-the-data-is-collected",children:"How the data is collected"}),"\n",(0,r.jsxs)(n.p,{children:["Electron's API documentation adheres to\n",(0,r.jsx)(n.a,{href:"https://github.com/electron/electron/blob/master/docs/development/coding-style.md",children:"Electron Coding Style"}),"\nand the\n",(0,r.jsx)(n.a,{href:"https://github.com/electron/electron/blob/master/docs/styleguide.md#readme",children:"Electron Styleguide"}),",\nso its content can be programmatically parsed."]}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.a,{href:"https://github.com/electron/electron-docs-linter",children:"electron-docs-linter"}),"\nis a new development dependency of the ",(0,r.jsx)(n.code,{children:"electron/electron"})," repository.\nIt is a command-line tool that lints all the markdown files and enforces the\nrules of the styleguide. If errors are found, they are listed and the release\nprocess is halted. If the API docs are valid, the ",(0,r.jsx)(n.code,{children:"electron-json.api"})," file\nis created and\n",(0,r.jsx)(n.a,{href:"https://github.com/electron/electron/releases/tag/v1.4.1",children:"uploaded to GitHub"}),"\nas part of the Electron release."]}),"\n",(0,r.jsx)(n.h2,{id:"standard-javascript-and-standard-markdown",children:"Standard Javascript and Standard Markdown"}),"\n",(0,r.jsxs)(n.p,{children:["Earlier this year, Electron's codebase was updated to use the\n",(0,r.jsx)(n.a,{href:"http://standardjs.com/",children:(0,r.jsx)(n.code,{children:"standard"})})," linter for all JavaScript. Standard's\nREADME sums up the reasoning behind this choice:"]}),"\n",(0,r.jsxs)(n.blockquote,{children:["\n",(0,r.jsx)(n.p,{children:"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."}),"\n"]}),"\n",(0,r.jsxs)(n.p,{children:["We also recently created\n",(0,r.jsx)(n.a,{href:"https://github.com/zeke/standard-markdown",children:"standard-markdown"})," to verify that\nall the JavaScript code snippets in our documentation are valid and consistent\nwith the style in the codebase itself."]}),"\n",(0,r.jsx)(n.p,{children:"Together these tools help us use continuous integration (CI) to automatically\nfind errors in pull requests. This reduces the burden placed on humans doing code\nreview, and gives us more confidence about the accuracy of our documentation."}),"\n",(0,r.jsx)(n.h3,{id:"a-community-effort",children:"A community effort"}),"\n",(0,r.jsx)(n.p,{children:"Electron's documentation is constantly improving, and we have our awesome\nopen-source community to thank for it. As of this writing, nearly 300 people\nhave contributed to the docs."}),"\n",(0,r.jsx)(n.p,{children:"We're excited to see what people do with this new structured data. Possible uses\ninclude:"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:["Improvements to ",(0,r.jsx)(n.a,{href:"https://electronjs.org/docs/",children:"https://electronjs.org/docs/"})]}),"\n",(0,r.jsxs)(n.li,{children:["A ",(0,r.jsx)(n.a,{href:"https://github.com/electron/electron-docs-linter/blob/master/README.md#typescript-definitions",children:"TypeScript definition file"})," for more streamlined Electron development in projects using TypeScript."]}),"\n",(0,r.jsxs)(n.li,{children:["Searchable offline documentation for tools like ",(0,r.jsx)(n.a,{href:"https://kapeli.com/dash",children:"Dash.app"})," and ",(0,r.jsx)(n.a,{href:"http://devdocs.io/",children:"devdocs.io"})]}),"\n"]})]})}function h(e={}){let{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,r.jsx)(n,{...e,children:(0,r.jsx)(l,{...e})}):l(e)}},28453(e,n,t){t.d(n,{R:()=>a,x:()=>i});var s=t(96540);let r={},o=s.createContext(r);function a(e){let n=s.useContext(o);return s.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function i(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(r):e.components||r:a(e.components),s.createElement(o.Provider,{value:n},e.children)}},47709(e){e.exports=JSON.parse('{"permalink":"/blog/api-docs-json-schema","source":"@site/blog/api-docs-json-schema.md","title":"Electron\'s API Docs as Structured Data","description":"Today
1we\'re announcing some improvements to Electron\'s documentation. Every new","date":"2016-09-27T00:00:00.000Z","tags":[{"inline":false,"label":"Website","permalink":"/blog/tags/website","description":"Updates on the electronjs.org website and docs"}],"readingTime":3.08,"hasTruncateMarker":false,"authors":[{"name":"zeke","url":"https://github.com/zeke","imageURL":"https://github.com/zeke.png?size=96","key":"zeke","page":null}],"frontMatter":{"title":"Electron\'s API Docs as Structured Data","date":"2016-09-27T00:00:00.000Z","authors":"zeke","slug":"api-docs-json-schema","tags":["website"]},"unlisted":false,"prevItem":{"title":"September 2016: New Apps","permalink":"/blog/september-2016-roundup"},"nextItem":{"title":"Electron Internals: Weak References","permalink":"/blog/electron-internals-weak-references"}}')}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.