5 articles tagués avec "Site web"

Le site Web d'Electron a un nouveau moteur de recherche qui fournit des résultats instantanés concernant la documentation des API, les tutoriels, les paquets npm liés à Electron, et plus encore.

L'apprentissage d'une nouvelle technologie ou d'un nouveau framework comme Electron peut être intimidant. Une fois la phase de démarrage rapide dépassée , il peut être difficile d'apprendre les meilleures pratiques ou de trouver les bonnes APIs, ou encore de découvrir les outils qui vous aideront à construire l'application de vos rêves. Notre désir est que le site web d'Electron soit un meilleur outil pour trouver les ressources dont vous avez besoin afin de vous peremettre de construire des applications rapidement et facilement.

Quelle que soit la page où vous vous trouvez sur electronjs.org la nouvelle zone de saisie de recherche est située en haut de la page.

Moteur de recherche​

Lorsque nous avons décidé d'ajouter une recherche au site web, nous avons mis en place notre propre moteur de recherche en utilisant GraphQL comme backend. Cela a été un plaisir de travailler avec GraphQL et le moteur de recherche était performant , mais, nous avons rapidement réalisé que ce n'était pas si trivial de construire un moteur de recherche. Les choses comme la recherche par mots multiples ou la détection des fautes de frappe nécessitent beaucoup de travail pour que cela fonctionne correctement. Donc, plutôt que de réinventer la roue, nous avons décidé d'utiliser une solution de recherche existante : Algolia.

Algolia est un service de recherche hébergé qui est devenu rapidement le moteur de recherche favori au sein de projets open source populaires tels que React, Vue, Bootstrap, Yarn et bien d'autres encore.

Voici quelques-unes des fonctionnalités qui ont fait d'Algolia un choix parfaitement adapté au projet Electron :

• InstantSearch.js fournit des résultats au fur et à mesure que vous tapez, et généralement dans la ms qui suit.
• La tolérance aux fautes de frappe signifie que vous obtiendrez toujours des résultats même lorsque vous tapez par exemple widnow.
• La syntaxe de requête avancée autorise"exact quoted matches" et -exclusion.
• Les clients de API sont open source et bien documentés.
• Des analyses sont produites nous disant ce que les gens recherchent le plus, ainsi que leurs recherches qui n'ont pas abouties. Cela nous permettra de mieux comprendre en quoi la documentation d'Electron peut être améliorée.
• Algolia est gratuit pour les projets open source.

Documentation de l'API​

Parfois, vous savez ce que ce que vous voulez accomplir, mais sans savoir exactement comment le faire. Electron possède plus de 750 méthodes d'API, événements et propriétés. Aucun humain ne peut se souvenir facilement de tous ces éléments, par contre les ordinateurs sont bons à cet égard. En utilisant les données structurées en JSON des API d'Electron, nous avons indexé toutes ces données dans Algolia, et vous pouvez ainsi, facilement trouver exacterment l'API que vous recherchez.

Vous essayez de redimensionner une fenêtre? Recherchez redimensionner et sautez directement à la méthode dont vous avez besoin.

Tutoriels​

Electron a une collection toujours croissante de tutoriels pour compléter sa documentation. Maintenant vous trouverez plus facilement des tutoriels sur un sujet donné, en sus de la documentation de l'API associée.

Vous recherchez les bonnes pratiques en matière de sécurité ? Recherchez sécurité.

Packages npm​

Il y a maintenant plus de 700 000 packages dans le registre npm et ce n'est pas toujours facile d'y trouver celui dont vous avez besoin. Pour vous y retrouver plus facilement parmi tous ces modules, nous avons créé electron-npm-packages, une collection des plus de 3400 modules du registre construits spécifiquement pour être utilisés avec Electron.

Les gens de Bibliothèques. o ont créé SourceRank, un système de notation de projets logiciels basé sur une combinaison de facteurs comme le code, la communauté, la documentation et l'utilisation. Nous avons créé un module sourceranks qui inclut le score obtenu par chaque module dans le registre npm, et nous utilisons ces scores pour trier les résultats.

Vous voulez des solutions de rechange aux modules IPC intégrés à Electron? Recherche de is:package ipc.

Applications Electron​

Il est facile d'indexer des données avec Algolia, nous avons donc ajouté la liste des applications existantes depuis electron/apps.

Essayez une recherche pour [musique] ou [homebrew].

Filtrage des résultats​

Si vous avez déja utilisé la recherche de code de GitHub, vous êtes probablement habitué aux filtres par clé-valeur tels que extension:js ou user:defunkt. Nous avons considéré que puisque cette technique de filtrage est très efficace, et nous vons donc ajouter le mot-clé is: à la recherche d'Electron qui vous permett de filtrer les résultats pour n'afficher qu'un seul type:

• is:api thumbnail
• is:tutorial security
• is:package ipc
• is:app graphql

Navigation au clavier​

Les gens aiment les raccourcis clavier ! La nouvelle recherche peut être utilisée entièrement au clavier:

• / donne le focus au champ de saisie
• esc donne le focus au champ de saisie et le vide
• down se déplace jusqu'au résultat suivant
• up se déplace au résultat précédent ou au champ de saisie
• enter ouvre un résultat

Nous avons également rendu lopen-source es sources du module qui permet cette interaction avec le clavier. Il est conçu pour être utilisé avec Algolia InstantSearch, mais est suffisament générique pour permettre la compatibilité avec différentes implémentations de recherche.

Votre avis nous est nécessaire​

Nous voulons avoir de vos nouvelles si vous rencontrez des problèmes avec le nouvel outil de recherche!

La meilleure façon de soumettre vos commentaires est de déposer un problème sur GitHub dans le dépôt approprié :

• electron/electronjs.org: Le site Electron. C'est le meilleur choix si vous ne savez pas où exposer un problème.
• electron/algolia-index est l'endroit où toutes les données Electron interrogeables sont compilées.
• electron/search-with-your-keyboard rend l'interface de recherche navigable par clavier.
• algolia/instantsearch.js est le client côté navigateur qui permet la recherche de type trouvez-dès-que-vous saisissez.
• algolia/algoliasearch-client-javascript est le client Node.js pour le téléchargement de données sur les serveurs d'Algolia.

Merci​

Remerciements spéciaux à Emily Jordan et Vanessa Yuen pour avoir produit ces nouvelles fonctionnalités de recherche, à Librairies.io pour la fourniture de scores SourceRank et à l'équipe d'Algolia pour leur aide lors du démarrage. 🍹

Depuis le lancement du nouveau site web Electron internationalisé nous avons travaillé dur pour rendre le développement d'Electron encore plus accessible aux développeurs en dehors du monde anglophone.

Voici donc quelques mises à jour passionnantes pour i18n!

🌐 Passage d'une langue à l'autre​

Saviez-vous que de nombreuses personnes qui lisent une documentation traduite font souvent des recoupements avec la documentation originale en anglais? Ils le font pour se familiariser avec la documentation en anglais et éviter les traductions obsolètes ou inexactes, problèmes que l'on peut rencontrer dans les documentations internationalisées.

Pour faciliter le renvoi vers la documentation anglaise, nous avons récemment fourni une fonctionnalité qui vous permet d'activer/désactiver de façon transparente une section de la documentation d'Electron entre l'anglais et la langue dans laquelle vous consultez le site. Le bouton de changement de langue s'affichera à partir du moment où vous aurez sélectionné une locale non anglaise sur le site web.

⚡ Accès rapide à la page de traduction​

Notice a typo or an incorrect translation while you're reading the documentation? You no longer have to log in to Crowdin, pick your locale, find the file you'd like the fix, etc etc. Instead, you can just scroll down to the bottom of the said doc, and click "Translate this doc" (or the equivalent in your language). Voila! Vous êtes directement dirigé vers la page de traduction de Crowdin. Now apply your translation magic!

📈 Quelques statistiques​

Ever since we have publicized the Electron documentation i18n effort, we have seen huge growth in translation contributions from Electron community members from all around the world. To date, we have 1,719,029 strings translated, from 1,066 community translators, and in 25 languages.

Here is a fun graph showing the approximate amount of time needed to translate the project into each language if the existing tempo (based on the project activity during the last 14 days at the time of writing) is preserved.

📃 Translator Survey​

We would like to give a huge ❤️ thank you ❤️ to everyone who has contributed their time to help improving Electron! In order to properly acknowledge the hard work of our translator community, we have created a survey to collect some information (namely the mapping between their Crowdin and Github usernames) about our translators.

If you are one of our incredible translators, please take a few minutes to fill this out: https://goo.gl/forms/b46sjdcHmlpV0GKT2.

🙌 Node's Internationalization Effort​

Because of the success of Electron's i18n initiative, Node.js decided to model their revamped i18n effort after the pattern we use as well! 🎉 The Node.js i18n initiative has now been launched and gained great momentum, but you can stil read about the early proposal and reasoning behind it here.

🔦 Contributing Guide​

If you're interested in joining our effort to make Electron more international friendly, we have a handy-dandy contributing guide to help you get started. Happy internationalizing! 📚

Electron a maintenant un nouveau site web sur electronjs.org! Nous avons remplacé notre site statique Jekyll par un serveur Node.js, nous donnant la flexibilité d'internationaliser le site et ouvrant la voie à de nouvelles fonctionnalités plus excitantes.

🌍 Traductions​

Nous avons entamé le processus d’internationalisation du site avec comme objectif de rendre le développement d’applications Electron accessible mondiallement aux développeurs. Nous utilisons désormais la plateforme de localisation appelée Crowdin qui s'intègre avec GitHub, l’ouverture et la mise à jour des requêtes de tirage automatiquement que le contenu est traduit dans différentes langues.

Bien que nous y ayons jusqu’à présent travaillé tranquillement , plus de 75 membres de la communauté Electron ont déjà découvert le projet organiquement et unis dans l’effort d’internationaliser le site afin de traduire les documents d’Electron en plus de 20 langues. We are seeing daily contributions from people all over the world, with translations for languages like French, Vietnamese, Indonesian, and Chinese leading the way.

Pour choisir votre langue et voir la progression de la traduction, visitez electronjs.org/languages

Si vous êtes polyglotte et que vous souhaitez aider à traduire les documents d'Electron et le site Web, visitez le dépôt electron/electron-i18n , ou passez directement à la traduction sur Crowdin, où vous pouvez vous connecter en utilisant votre compte GitHub.

There are currently 21 languages enabled for the Electron project on Crowdin. Adding support for more languages is easy, so if you're interested in helping translate but you don't see your language listed, let us know and we'll enable it.

Raw Translated Docs​

If you prefer to read documentation in raw markdown files, you can now do that in any language:

git clone https://github.com/electron/electron-i18n
ls electron-i18n/content

App Pages​

As of today, any Electron app can easily have its own page on the Electron site. For a few examples, check out Etcher, 1Clipboard, or GraphQL Playground, pictured here on the Japanese version of the site:

There are some incredible Electron apps out there, but they're not always easy to find, and not every developer has the time or resources to build a proper website to market and distribute their app.

Using just a PNG icon file and a small amount of app metadata, we're able to collect a lot of information about a given app. Using data collected from GitHub, app pages can now display screenshots, download links, versions, release notes, and READMEs for every app that has a public repository. Using a color palette extracted from each app's icon, we can produce bold and accessible colors to give each app page some visual distinction.

The apps index page now also has categories and a keyword filter to find interesting apps like GraphQL GUIs and p2p tools.

Si vous avez une application Electron que vous aimeriez voir sur le site, ouvrez une pull request sur le dépôt electron/electron-apps.

One-line Installation with Homebrew​

Le gestionnaire de paquets Homebrew pour macOS a une sous-commande appelée cask qui facilite l'installation d'applications de bureau en utilisant une seule commande dans votre terminal, comme brew cask install atom.

We've begun collecting Homebrew cask names for popular Electron apps and are now displaying the installation command (for macOS visitors) on every app page that has a cask:

To view all the apps that have homebrew cask names, visit electronjs.org/apps?q=homebrew. If you know of other apps with casks that we haven't indexed yet, please add them!

🌐 Un nouveau domaine​

Nous avons déplacé le site de electron.atom.io vers un nouveau domaine : electronjs.org.

The Electron project was born inside Atom, GitHub's open-source text editor built on web technologies. Electron was originally called atom-shell. Atom was the first app to use it, but it didn't take long for folks to realize that this magical Chromium + Node runtime could be used for all kinds of different applications. When companies like Microsoft and Slack started to make use of atom-shell, it became clear that the project needed a new name.

And so "Electron" was born. In early 2016, GitHub assembled a new team to focus specifically on Electron development and maintenance, apart from Atom. In the time since, Electron has been adopted by thousands of app developers, and is now depended on by many large companies, many of which have Electron teams of their own.

Soutenir les projets Electron de GitHub comme Atom et GitHub Desktop reste une priorité pour notre équipe, mais en passant à un nouveau domaine, nous espérons contribuer à clarifier la distinction technique entre Atom et Electron.

🐢🚀 Node.js Everywhere​

Le site Web précédent d'Electron a été construit avec Jekyll, le générateur de site statique populaire basé sur Ruby. Jekyll is a great tool for building static websites, but the website had started to outgrow it. Nous voulions des capacités plus dynamiques comme des redirections appropriées et un rendu de contenu dynamique, donc un serveur Node.js était le choix évident.

The Electron ecosystem includes projects with components written in many different programming languages, from Python to C++ to Bash. But JavaScript is foundational to Electron, and it's the language used most in our community.

By migrating the website from Ruby to Node.js, we aim to lower the barrier to entry for people wishing to contribute to the website.

⚡️ Easier Open-Source Participation​

Si vous avez Node.js (8 ou plus) et git installé sur votre système, vous pouvez facilement faire fonctionner le site localement :

git clone https://github.com/electron/electronjs.org
cd electronjs.org
npm install
npm run dev

The new website is hosted on Heroku. We use deployment pipelines and the Review Apps feature, which automatically creates a running copy of the app for every pull request. This makes it easy for reviewers to view the actual effects of a pull request on a live copy of the site.

🙏 Merci aux contributeurs​

We'd like to give special thanks to all the folks around the world who have contributed their own time and energy to help improve Electron. The passion of the open-source community has helped immeasurably in making Electron a success. Merci !

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:

• Améliorations de https://electronjs.org/docs/
• Un fichier de définition de TypeScript pour un développement Electron plus simplifié dans les projets utilisant TypeScript.
• Documentation interrogeable hors ligne pour des outils tels que Dash.app et devdocs.io

Cette semaine, nous avons hébergé la documentation d'Electron sur electronjs.org. Vous pouvez visiter /docs/latest pour la dernière série de documents. We'll keep versions of older docs, too, so you're able to visit /docs/vX.XX.X for the docs that correlate to the version you're using.

You can visit /docs to see what versions are available or /docs/all to see the latest version of docs all on one page (nice for cmd + f searches).

Si vous souhaitez contribuer au contenu du répertoire docs, vous pouvez le faire en accédant au dépôt Electron, où sont récupéré les documentation. Nous les récupérons pour chaque version mineure et les ajoutons au dépôt du site Electron, qui est produit à l'aide de Jekyll.

Si vous souhaiter en savoir plus sur la façon dont nous extrayons les documents d'un dépôt vers un autre, continuez à lire ci-dessous. Sinon, profitez des docs!

The Technical Bits​

We're preserving the documentation within the Electron core repository as is. Cela signifie que electron/electron aura toujours la dernière version des documents. When new versions of Electron are released, we duplicate them over on the Electron website repository, electron/electronjs.org.

script/docs​

To fetch the docs we run a script with a command line interface of script/docs vX.XX.X with or without the --latest option (depending on if the version you're importing is the latest version). Our script for fetching docs uses a few interesting Node modules:

• nugget for getting the release tarball and saving it to a temporay directory.
• gunzip-maybe to unzip the tarball.
• tar-fs pour streamer juste le dossier /docs depuis le tarball et filtrer et traiter les fichiers (avec l'aide de through2) afin qu'ils fonctionne bien avec notre site Jekyll site (plus à ce sujet ci-dessous).

Tests help us know that all the bits and pieces landed as expected.

Jekyll​

The Electron website is a Jekyll site and we make use of the Collections feature for the docs with a structure like this:

electron.atom.io
└── _docs
    ├── latest
    ├── v0.27.0
    ├── v0.26.0
    ├── so on
    └── so forth

Front matter​

For Jekyll to render each page it needs at least empty front matter. We're going to make use of front matter on all of our pages so while we're streaming out the /docs directory we check to see if a file is the README.md file (in which case it receives one front matter configuration) or if it is any other file with a markdown extension (in which case it receives slightly different front matter).

Each page receives this set of front matter variables:

---
version: v0.27.0
category: Tutorial
title: 'Quick Start'
source_url: 'https://github.com/electron/electron/blob/master/docs/tutorial/quick-start.md'
---

The README.md gets an additional permalink so that has a URL has a common root of index.html rather than an awkward /readme/.

permalink: /docs/v0.27.0/index.html

Config and Redirects​

In the site's _config.yml file a variable latest_version is set every time the --latest flag is used when fetching docs. We also add a list of all the versions that have been added to the site as well as the permalink we'd like for the entire docs collection.

latest_version: v0.27.0
available_versions:
  - v0.27.0
collections:
  docs: { output: true, permalink: '/docs/:path/' }

The file latest.md in our site root is empty except for this front matter which allows users to see the index (aka README) of the latest version of docs by visiting this URL, electron.atom.io/docs/latest, rather than using the latest version number specifically (though you can do that, too).

---
permalink: /docs/latest/
redirect_to: /docs/{{ site.data.releases[0].version }}
---

Layouts​

In the docs.html layout template we use conditionals to either show or hide information in the header and breadcrumb.

{% raw %} {% if page.category != 'ignore' %}
<h6 class="docs-breadcrumb">
  {{ page.version }} / {{ page.category }} {% if page.title != 'README' %} / {{
  page.title }} {% endif %}
</h6>
{% endif %} {% endraw %}

To create a page showing the versions that are available we just loop through the list in our config on a file, versions.md, in the site's root. Also we give this page a permalink: /docs/

{% raw %} {% for version in site.available_versions %} - [{{ version
}}](/docs/{{ version }}) {% endfor %} {% endraw %}

Hope you enjoyed these technical bits! Si vous désirez en savoir plus sur l'utilisation de Jekyll pour les sites de documentation, allez jeter un oeil sur comment l'équipe de docs de GitHub publie la documentation de GitHub sur Jekyll.