Skip to main content

作为结构化数据的 Electron API 文档

· 6 min read
zeke

今天我们宣布对 Electron 文档进行一些改进。每个新版本现在都包含一个JSON 文件，详细描述了所有 Electron 的公共 API。我们创建此文件是为了让开发者能够以有趣的新方式使用 Electron 的 API 文档。

🌐 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.

架构概述​

🌐 Schema overview

每个 API 都是一个具有名称、描述、类型等属性的对象。像 BrowserWindow 和 Menu 这样的类还有额外的属性，用于描述它们的实例方法、实例属性、实例事件等。

🌐 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.

以下是描述 BrowserWindow 类的模式摘录：

🌐 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: 'https://electron.nodejs.cn/docs/api/browser-window',
  repoUrl: 'https://github.com/electron/electron/blob/v1.4.0/docs/api/browser-window.md',
  staticMethods: [...],
  instanceMethods: [...],
  instanceProperties: [...],
  instanceEvents: [...]
}

下面是一个方法描述的示例，在本例中是 apis.BrowserWindow.instanceMethods.setMaximumSize 实例方法：

🌐 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'
  }]
}

使用新数据​

🌐 Using the new data

为了让开发者在项目中更方便地使用这些结构化数据，我们创建了 electron-docs-api，这是一个小型的 npm 包，每当有新的 Electron 版本发布时，它会自动发布。

🌐 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

为了立即获得满足，请在你的 Node.js REPL 中试用该模块：

🌐 For instant gratification, try out the module in your Node.js REPL:

npm i -g trymodule && trymodule electron-api-docs=apis

数据如何收集​

🌐 How the data is collected

Electron 的 API 文档遵循 Electron 编码规范 和 Electron 风格指南，因此其内容可以通进程序进行解析。

🌐 Electron's API documentation adheres to Electron Coding Style and the Electron Styleguide, so its content can be programmatically parsed.

electron-docs-linter 是 electron/electron 仓库的新开发依赖。它是一个命令行工具，用于检查所有的 Markdown 文件并强制执行风格指南的规则。如果发现错误，会列出这些错误并暂停发布进程。如果 API 文档有效，则会创建 electron-json.api 文件，并作为 Electron 发布的一部分上传到 GitHub。

🌐 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.

标准 Javascript 和标准 Markdown​

🌐 Standard Javascript and Standard Markdown

今年早些时候，Electron 的代码库已更新为对所有 JavaScript 使用 standard linter。Standard 的自述文件总结了选择这一做法的原因：

🌐 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:

采用标准风格意味着将代码清晰度和社区约定的重要性置于个人风格之上。这可能并不适用于100%的项目和开发文化，但开源社区对新手来说可能是一个充满挑战的环境。建立明确、自动化的贡献者预期可以让项目更加健康。

我们最近还创建了 standard-markdown 来验证我们文档中的所有 JavaScript 代码片段是否有效，并且与代码库本身的风格一致。

🌐 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.

这些工具一起帮助我们使用持续集成（CI）自动发现拉取请求中的错误。这减少了人工进行代码审查的负担，并使我们对文档的准确性更有信心。

🌐 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.

社区成果​

🌐 A community effort

Electron 的文档在不断改进，这要感谢我们出色的开源社区。截至撰写本文时，已有近 300 人为文档做出了贡献。

🌐 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: