Перейти к основному содержанию

Electron's API Docs as Structured Data

· 3 мин. прочитано
zeke
zeke

Сегодня мы объявляем о некоторых улучшениях в документации Electron. Каждый новый релиз теперь включает в себя файл JSON, который описывает всё об публичных API Electron в деталях. Мы создали этот файл, чтобы разработчики могли использовать документацию Electron API новыми интересными способами.

Обзор схемы​

Каждое API - это объект со свойствами по типу имени, описания, типа и т.д. Такие классы, как BrowserWindow и Menu имеют дополнительные свойства, описывающие методы, свойства, события и т.п. их экземпляра.

Вот пример из схемы, которая описывает класс BrowserWindow:

{
  имя: 'BrowserWindow',
  описание: 'Создание и управление окнами браузера. ,
  процесс: {
    main: true,
    renderer: false
  },
  тип: 'Класс',
  exanceName: 'win',
  слаг: 'browser-window',
  websiteUrl: 'https://electronjs. rg/docs/api/browser-window',
  repoUrl: 'https://github.com/electron/electron/blob/v1.4.0/docs/api/browser-window. d',
  staticMethods: [...],
  instanceMethods: [...],
  instanceProperties: [...],
  instanceEvents: [...]
}
}

И вот пример описания метода, в данном случае метод apis.BrowserWindow.instanceMethods.setMaximumSize экземпляра:

{
  name: 'setMaximumSize',
  signature: '(width, height)',
  description: 'Устанавливает максимальный размер окна по ширине и высоте.',
  parameters: [{
    name: 'width',
    type: 'Integer'
  }, {
    name: 'height',
    type: 'Integer'
  }]
}

Использование новых данных​

Чтобы сделать использование этих структурированных данных в своих проектах для разработчиков простым, мы создали electron-docs-api, небольшой пакет npm, который публикуется автоматически с каждым новым релизом Electron.

npm install electron-api-docs --save

Для мгновенного удовлетворения попробуйте модуль в Node.js REPL:

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

Как данные собираются​

Документация Electron API придерживается стиля кода Electron и гайдов по стилю Electron, поэтому его содержимое может быть автоматически обработан.

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.

Standard Javascript and Standard Markdown​

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.

A community effort​

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: