Aller au contenu principal

Les documents de l'API d’Electron en tant que données structurées

· 4 mins de lecture
zeke

Nous annonçons aujourd’hui, quelques améliorations de la documentation d’Electron. Chaque nouvelle version inclut désormais un fichier JSON décrivant en détail toutes les API publiques d’Electron. Nous avons créé ce fichier pour permettre aux développeurs d’utiliser la documentation de l’API d’Electron de manière plus intéressante.

Aperçu du schéma​

Chaque API est un objet avec des propriétés telles que nom, description, type, etc. Les classes telles que BrowserWindow et Menu ont des propriétés supplémentaires décrivant leurs méthodes d’instance, propriétés d’instance, événements d’instance, etc.

Voici un extrait du schéma décrivant la classe BrowserWindow:

{
  nom: 'BrowserWindow', description
  : 'Créer et contrôler les fenêtres du navigateur.', processus
  : {
    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: [...]
}

Et cet autre exemple exemple de description dune méthode, ici, la méthode d'instance apis.BrowserWindow.instanceMethods.setMaximumSize:

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

Utilisation de ces nouvelles données​

Pour faciliter l'utilisation de ces données structurées dans leurs projets par les développeurs, nous avons créé electron-docs-api, un petit package npm publié automatiquement chaque fois qu'il y a une nouvelle version d'Electron .

npm install electron-api-docs --save

Pour une appréciation rapide, essayez le module dans votre REPL Node.js :

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

Comment les données sont collectées​

La documentation API d'Electron adhère à Electron Coding Style et au Electron Styleguide et donc son contenu peut être analysé par programme.

Le electron-docs-linter est une nouvelle dépendance de développement du dépôt electron/electron. C'est un outil en ligne de commande qui effectue un lint de tous les fichiers markdown et applique les règles du styleguide. Si des erreurs sont trouvées, elles sont listées et le processus de publication est interrompu. Si les docs de l'API sont valides, le fichier electron-json.api est créé et téléchargé sur GitHub pour être inclus dans la version d'Electron.

Javascript standard et Markdown standard​

Plus tôt dans l'année, la base de code d'Electron a été mise à jour pour utiliser le linter standard pour tout JavaScript. Le README de Standard résume le raisonnement derrière ce choix :

L'adoption d'un style standard donne plus dl'importance à la clarté du code et des conventions communautaires que le style personnel. Cela n'est peut être pas judicieux pour 100 % des projets et des cultures de développement, toutefois l'open source peut être un environnement hostile pour les débutants. La mise en place d’attentes claires et automatisées des contributeurs rend un projet plus sain.

Nous avons également récemment créé markdown-standard pour vérifier que tous les snippets de code JavaScript de notre documentation sont valides et cohérents avec le style de la base de code elle-même.

Ensemble, ces outils nous aident à utiliser l'intégration continue (CI) pour trouver automatiquement des erreurs dans les pull requests. Cela réduit le fardeau imposé aux humains qui effectuent la revue du code et nous donne plus de confiance quant à l’exactitude de notre documentation.

Un effort de la communauté​

La documentation d’Electron s’améliore constamment, et nous devons remercier notre formidable communauté open-source pour cela. Au moment d’écrire ces lignes, près de 300 personnes ont contribué aux documents.

Nous sommes heureux de voir ce que les gens font avec ces nouvelles données structurées. Utilisations possibles: