Skip to main content

Electron의 API 문서를 구조화된 데이터로

· 6 min read
zeke
zeke

오늘 Electron 문서에 몇 가지 개선 사항을 발표한다. 이제 모든 새로운 릴리스에는 Electron의 모든 공개 API를 상세히 설명하는 JSON 파일이 포함된다. 개발자들이 Electron의 API 문서를 새로운 방식으로 활용할 수 있도록 이 파일을 만들었다.

스키마 개요​

각 API는 name, description, type 등의 속성을 가진 객체로 구성된다. BrowserWindow와 Menu 같은 클래스는 인스턴스 메서드, 인스턴스 속성, 인스턴스 이벤트 등을 설명하는 추가 속성을 포함한다.

다음은 BrowserWindow 클래스를 설명하는 스키마의 일부이다:

{
  name: 'BrowserWindow',
  description: '브라우저 윈도우를 생성하고 제어한다.',
  process: {
    main: true,
    renderer: false
  },
  type: 'Class',
  instanceName: 'win',
  slug: 'browser-window',
  websiteUrl: 'https://electronjs.org/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 인스턴스 메서드의 설명이다:

{
  name: 'setMaximumSize',
  signature: '(width, height)',
  description: '윈도우의 최대 크기를 width와 height로 설정한다.',
  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 스타일 가이드를 준수한다. 이 때문에 문서의 내용을 프로그래밍 방식으로 파싱할 수 있다.

electron-docs-linter는 electron/electron 저장소의 새로운 개발 의존성이다. 이 도구는 커맨드라인에서 모든 마크다운 파일을 검사하고 스타일 가이드의 규칙을 강제한다. 오류가 발견되면 해당 오류를 나열하고, 릴리스 프로세스를 중단한다. API 문서가 유효한 경우 electron-json.api 파일이 생성되고, GitHub에 업로드되어 Electron 릴리스의 일부로 포함된다.

표준 자바스크립트와 표준 마크다운​

올해 초, Electron의 코드베이스는 모든 자바스크립트 파일에 대해 standard 린터를 사용하도록 업데이트되었다. Standard의 README는 이 선택의 이유를 다음과 같이 요약하고 있다:

표준 스타일을 채택한다는 것은 코드의 명확성과 커뮤니티 규약을 개인적인 스타일보다 우선시한다는 의미이다. 이는 모든 프로젝트와 개발 문화에 적합하지 않을 수 있지만, 오픈소스는 초보자에게 가혹한 환경이 될 수 있다. 명확하고 자동화된 기여자 기대치를 설정하면 프로젝트가 더 건강해진다.

또한 최근에는 standard-markdown을 만들어 문서에 포함된 모든 자바스크립트 코드 조각이 유효하고 코드베이스의 스타일과 일치하는지 확인하고 있다.

이 두 도구를 함께 사용하면 지속적 통합(CI)을 통해 풀 리퀘스트에서 오류를 자동으로 찾을 수 있다. 이를 통해 코드 리뷰를 하는 사람들의 부담을 줄이고, 문서의 정확성에 대한 신뢰를 더욱 높일 수 있다.

커뮤니티의 노력​

Electron 문서는 지속적으로 개선되고 있으며, 이는 오픈소스 커뮤니티의 큰 기여 덕분이다. 이 글을 쓰는 시점에서 거의 300명이 문서에 기여했다.

이 새로운 구조화된 데이터로 사람들이 어떤 일을 해낼지 기대가 크다. 가능한 활용 사례는 다음과 같다:

Electron 커뮤니티의 활발한 참여가 문서 품질을 높이는 데 큰 역할을 하고 있다. 이러한 노력은 개발자들이 Electron을 더 쉽게 이해하고 활용할 수 있도록 돕는다. 앞으로도 더 많은 사람들이 참여해 문서를 발전시켜 나가길 기대한다.