"ウェブサイト" タグの記事が 1 件の投稿 件あります

Electron のウェブサイトに、APIドキュメント、チュートリアル、Electron 関連の npm パッケージなどを瞬時に検索できる新しい検索エンジンを導入しました。

Electron のような新しい技術やフレームワークを覚えるのは大変なことです。 クイックスタート の段階を過ぎると、ベストプラクティスを学んだり、適切な API を見つけたり、夢のアプリを構築するのに役立つツールを発見したりするのが難しくなっていきます。 Electron のウェブサイトを、より早く、より簡単なアプリ構築のために必要なリソースを探せるようなより良いツールにしたいと考えています。

electronjs.org の任意のページにアクセスすると、ページ上部に新しい検索欄が表示されます。

検索エンジン​

ウェブサイトに検索を追加しようと思った当初は、バックエンドに GraphQL を使った独自の検索エンジンを試運転しました。 GraphQL の作業は楽しく、検索エンジンは高パフォーマンスでしたが、この構築は分かりきった作業ではないとすぐに気づきました。 複数語での検索やタイプミス検出のようなものは、正しく動くために多くの作業を必要とします。 車輪を再発明するのではなく、既存の検索ソリューションである Algolia を使用することにしました。

Algolia は、React、Vue、Bootstrap、Yarn、その他多数 の人気オープンソースプロジェクトの間で急速に選ばれる検索エンジンとなったホスト型検索サービスです。

ここでは、Algolia が Electron プロジェクトに適していた機能をいくつか紹介します。

• InstantSearch.js はタイプして通常 1ms 以内に結果を提供します。
• タイプミス寛容性 により [widnow] と入力しても結果が得られます。
• 高度なクエリ構文 により "引用符で囲まれた完全一致" と -除外 ができます。
• API クライアント はオープンソースで、十分にドキュメント化されています。
• 分析 により頻繁に検索されるものや、検索しても見つけらないものがわかります。 これにより、Electron のドキュメントの改善策について、貴重な知見を得ることができます。
• Algolia は オープンソースプロジェクトのための無料 です。

APIドキュメント​

時折、何を達成したいか 分かっていても、どのように それを行うかが正確に分からないことがあります。 Electron には 750 以上の API メソッド、イベント、プロパティがあります。 人間は簡単に全部覚えられませんが、コンピュータにとっては得意分野です。 Electron の JSON API ドキュメント を利用して、Algolia にあるすべてのデータをインデックス化し、探している APIを簡単に見つけられます。

ウインドウをサイズ変更してみたいのですか? [resize] で検索して、必要なメソッドに直接ジャンプしましょう。

チュートリアル​

Electron では、API ドキュメントを補完するチュートリアルのコレクションが増え続けています。 これで、関連する API ドキュメントと一緒に、特定トピックのチュートリアルもより簡単に見つけられるようになりました。

セキュリティのベストプラクティスをお探しですか? [security] と検索しましょう。

npm パッケージ​

npm レジストリには現在 70 万以上のパッケージがあり、必要なパッケージを見つけるのは簡単ではありません。 これらのモジュールをより簡単に探せるように、Electron 向けに特別に作られた 3400 以上のモジュールを集めた electron-npm-packages を作成しました。

Libraries.io の方々は、コード、コミュニティ、ドキュメント、使用状況などのメトリクスの組み合わせに基づいてソフトウェアプロジェクトをスコアリングするシステム、SourceRank を作成しています。 これらのスコアを使って、npm レジストリ内のすべてのモジュールのスコアを含む [sourceranks] モジュールを作成しパッケージの結果をソートしています。

Electron 内蔵の IPC モジュールの代替品をお探しですか? is:package ipc と検索しましょう。

Electron アプリ​

Algolia でのデータのインデックスは簡単 なので、electron/apps から既存アプリのリストを追加しました。

[music] や [homebrew] と検索してみてください。

結果のフィルタリング​

GitHub の コード検索 を使ったことがある人なら、extension:js や user:defunkt のようなコロンで区切られたキーバリューフィルタが存在すると気づいているでしょう。 このフィルタリング技術は非常に強力なものであると考えており、Electron の検索に is: キーワードを追加しました。これにより、一種類の結果のみを表示するようにフィルタできます。

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

キーボードナビゲーション​

キーボードショートカットはみんな大好き! キーボードから指を離さずに検索できるようになっています。

• / 検索欄にフォーカス
• esc 検索欄にフォーカスしてそれを消去
• down 次の結果に移動
• up 前の結果か検索欄に移動
• enter 結果を開く

また、このキーボード操作を可能にする モジュール もオープンソース化しました。 Algolia InstantSearch 用に設計されていますが、他の検索実装と互換になるように一般化してあります。

フィードバック募集中​

新しい検索ツールで何か問題が発生した場合は、それについてお聞かせください!

フィードバックを提出する最善の方法は、GitHub で適切なリポジトリに Issue を提出することです。

• electron/electronjs.org は Electron のウェブサイトです。 どこに問題を提出すればよいかわからない場合は、これが最善の方法です。
• electron/algolia-indices は検索可能な Electron データすべてをコンパイルしてあります。
• electron/search-with-your-keyboard が検索インターフェイスをキーボードでナビゲーション可能にします。
• algolia/instantsearch.js はタイプして検索を有効にするブラウザ側のクライアントです。
• algolia/algoliasearch-client-javascript はデータを Algolia のサーバーにアップロードする Node.js クライアントです。

謝辞​

これらの新しい検索機能を構築してくださった Emily Jordan と Vanessa Yuen、Libraries.io のスコアを提供してくださった SourceRank 、そして私たちの活動を支援してくださった Algolia のチームに感謝します。 🍹

新しく国際化された Electron ウェブサイトの 立ち上げ 以来、英語圏以外の開発者が Electron の開発知識をさらに利用しやすいように取り組んでいます。

そこで、エキサイティングな国際化 (i18n) アップデートを紹介しましょう!

🌐 言語切替​

翻訳ドキュメントの読者の多くは、原文の英語ドキュメントも相互参照することが多いというのはご存知ですか? 古かったり不正確だったりする訳文を避けるために、英語ドキュメントを習熟しているのです。これは国際化されたドキュメントに鳴らされる警笛の一つです。

英語ドキュメントへの相互参照を容易にするため、Electron ドキュメントの文章を英語とウェブサイトの表示言語との間でシームレスに切り替えられる機能を追加しました。 ウェブサイトで英語以外のロケールを選択すれば、言語切替が表示されます。

⚡️ 訳文ページへのクイックアクセス​

ドキュメントを読んでいて、誤植や誤訳に気がつきましたか? もう Crowdin にログインしたり、ロケールを選択したり、修正したいファイルを見つけたりする必要はありません。 代わりに、ドキュメントの一番下までスクロールし、上記の [このドキュメントを改善する] をクリックするだけです。 一丁あがり! Crowdin の翻訳ページに直接移動します。 さあ、あなたの翻訳魔法を見せてごらん!

📈 統計​

Electron ドキュメント国際化 (i18n) の取り組みを公表して以来、世界中の Electron コミュニティメンバーからの翻訳の貢献が 爆発的に 増加してきています。 現在まで、1,719,029 の文字列が、1,066 人のコミュニティ翻訳者から 25 の言語で翻訳されています。

このままの (執筆時点での過去 14 日間のプロジェクトアクティビティに基づく) ペースが保たれた場合、各言語への翻訳プロジェクトに必要なおおよその時間を示してくれる、楽しいグラフです。

📃 翻訳者アンケート​

Electron の改善に時間を費やしてくださった皆さんに ❤️ありがとう❤️を! 翻訳者コミュニティのいかに勤勉かを正しく認識するため、翻訳者に関する情報 (すなわち Crowdin と Github のユーザー名の繋がり) を収集するアンケートを作成しました。

素晴らしい翻訳者の一員の方は、数分で済みますのでこちらからご記入ください。https://goo.gl/forms/b46sjdcHmlpV0GKT2

🙌 Node の国際化活動​

Electron の国際化イニシアチブが成功したことから、Node.js は私たちのパターンに沿った 改訂版の国際化活動 をモデル化することにしました! 🎉 Node.js 国際化イニシアチブ が開始され、大きな勢いを得ています。草案とその背景事由は こちら で読むことができます。

🔦 コントリビューションガイド​

Electron をより国際的で使いやすくする活動に興味がある方向けに、着手しやすいように手取り足取り解説している コントリビューションガイド があります。 国際化万歳! 📚

Electron の新しいウェブサイトは electronjs.org です! 静的な Jekyll サイトを Node.js ウェブサーバに置き換えました。これにより、サイトの国際化が柔軟になり、より魅力的な新機能への道が開かれました。

🌍 翻訳​

私たちは、世界中の開発者が Electron アプリ開発に着手できることを目標に、ウェブサイトの国際化プロセスを開始しました。 私たちは Crowdin という翻訳プラットフォームを使用しています。これは GitHub と統合されており、コンテンツが異なる言語に翻訳されると自動的にプルリクエストを開いて更新します。

私たちはこれまで静かにこの取り組みを進めていました。75 人以上もの Electron コミュニティメンバーは、すでにプロジェクトを組織的に構築し、Web サイトの国際化と、Electron のドキュメントを 20 以上の言語に翻訳する取り組みに参加しています。 翻訳における世界中の 日毎の貢献数 では、特にフランス語、ベトナム語、インドネシア語、中国語の言語が抜きんでています。

各言語を選択してその言語の翻訳の進捗状況を確認するには、 electronjs.org/languages を参照してください。

マルチリンガルの方で Electron のドキュメントやウェブサイトの翻訳に興味があれば、electron/electron-i18n のレポジトリにアクセスするか、Crowdin ですぐに翻訳を始められます。

現在 Crowdin の Electron 翻訳プロジェクトで有効な言語は 21 つです。 さらなる言語のサポート追加は簡単ですので、翻訳に興味があるもの翻訳したい言語がリストにない場合は、こちらからご連絡くだされば 有効にします。

レンダリング前の翻訳のドキュメント​

生の Markdown ファイルでドキュメントを読みたい場合でも、以下のようにすれば任意の言語で読むことができるようになりました。

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

アプリページ​

本日から、どのような Electron アプリでも、独自のページをこのサイト上へ簡単に作成できます。 例えば、Etcher や 1Clipboard や GraphQL Playground があります。ここではサイトの日本語版を示しています。

Electron には素晴らしいアプリがいくつもありますが、それらを見つけるのは簡単ではありませんし、すべての開発者がアプリを市場に出して頒布するために適切なウェブサイトを構築する時間やリソースを持っているわけではありません。

PNG アイコンファイルとアプリメタデータが少しあれば、特定のアプリに関する多くの情報を収集できます。 GitHub から収集したデータで、公開リポジトリがある全アプリのスクリーンショット、ダウンロードリンク、バージョン、リリースノート、README をアプリページに表示できるようになりました。 各アプリのアイコンから抽出したカラーパレットを使用しつつ、強調されたアクセシビリティの高い色 を作成し、各アプリページに視覚の分別をつけることもできます。

アプリのインデックスページ には、GraphQL GUI や p2p ツール のような面白いアプリを見つけられるように、カテゴリとキーワードフィルタが追加されました。

サイトで紹介したい Electron アプリがある方は、ぜひ electron/electron-apps リポジトリでプルリクエストを開いてください。

Homebrew でワンラインインストール​

macOS のパッケージマネージャー Homebrew には cask というサブコマンドがあります。brew cask install atom のようにすれば、ターミナル上のコマンド一つでデスクトップアプリを簡単にインストールできます。

人気の Electron アプリの Homebrew cask の名前の収集を開始し、cask があるすべてのアプリのページにインストールコマンド (macOS の訪問者向け) を表示するようにしました。

Homebrew cask の名前を持つすべてのアプリを表示するには、electronjs.org/apps?q=homebrew をご覧ください。 まだインデックスされていない cask のアプリをご存知でしたら、ぜひ追加してください!

🌐 新ドメイン​

このサイトを electron.atom.io から新しいドメインに移動しました: electronjs.org。

Electron プロジェクトは、ウェブ技術で構築した GitHub のオープンソーステキストエディタ Atom の中から生まれました。 Electron は元々 atom-shell と呼ばれていました。 最初に使用したアプリは Atom でしたが、ほどなくしてこの魔法のような Chromium + Node ランタイムがあらゆるタイプのアプリケーションにも利用できると気づきました。 Microsoft や Slack のような企業が atom-shell を利用し始めた頃、このプロジェクトには新しい名前が必要だろうということになりました。

そして "Electron" が生まれたのです。 2016 年の初め、GitHub は Atom と別に Electron の開発とメンテナンス特化の新チームを結成しました。 それ以来 Electron は何千ものアプリ開発者に採用されています。現在では多くの大企業に採用され、その多くが独自の Electron チームをも保有しています。

Atom や GitHub Desktop のような GitHub の Electron プロジェクトサポートも未だに私たちチームの優先事項です。しかし、新ドメインへの移行が Atom と Electron の技術的区別をより明確にできるであろうと願っています。

🐢🚀 どこでもNode.js​

以前の Electron ウェブサイトは、Ruby ベースの静的サイト生成ツールとして人気の Jekyll で構築していました。 Jekyll は静的ウェブサイトの構築に最適なツールですが、このウェブサイトではそれを使いこなせなくなり始めていました。 適切なリダイレクトや動的なコンテンツの描画等より動的な機能が欲しかったため、Node.js サーバーは当然の選択でした。

Electron のエコシステムには、Python から C++ や Bash まで、さまざまなプログラミング言語で書かれたコンポーネントのプロジェクトが含まれています。 しかし Electron の基礎は JavaScript であり、私たちのコミュニティで最も使用されている言語です。

ウェブサイトを Ruby から Node.js に移行することで、ウェブサイトに貢献したい人の敷居を低くすることが目標です。

⚡️ より簡単になったオープンソースへの参加​

Node.js (8 以降) と git をインストールしていれば、ローカルで簡単にサイトを動かせます。

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

この新しいウェブサイトはHerokuでホストされています。 デプロイパイプラインと アプリプレビュー 機能を使用しています。これにより、プルリクエストごとにアプリの動作するコピーを自動作成できます。 これにより、レビュアーはプルリクエストの実際の効果を、サイトの生き写しで簡単に確認できます。

🙏 貢献者への感謝​

Electron の改善に時間と労力を提供してくださった世界中の皆様に特別な感謝の意を表したいと思います。 オープンソースコミュニティの情熱が Electron の成功を大きく支えています。 ありがとうございます!

本日、Electron のドキュメントに対していくつか改善する点を発表します。 新しいリリースごとに、Electron のすべての公開 API を詳細に説明する JSON ファイル を同梱します。 このファイルを作成したことで、開発者は Electron の API ドキュメントの面白くて新しい使用方法ができるようになりました。

スキーマの概要​

各 API は、名前、説明、型などの特性を持つオブジェクトです。 BrowserWindow や Menu のようなクラスには、インスタンスメソッド、インスタンスプロパティ、インスタンスイベントなどもあります。

以下は BrowserWindow クラスを説明しているスキーマからの抜粋です。

{
  name: 'BrowserWindow',
  description: 'Create and control browser windows.',
  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: 'Sets the maximum size of window to width and height.',
  parameters: [{
    name: 'width',
    type: 'Integer'
  }, {
    name: 'height',
    type: 'Integer'
  }]
}

新しいデータを使う​

開発者がプロジェクトでこの構造化データを簡単に使用できるように、新しい Electron リリースごとに自動公開される小さな npm パッケージ electron-docs-api を作成しました。

npm install electron-api-docs --save

すぐに試したいなら、Node.js REPL 内でこのモジュールを試してみてください。

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

データの収集方法​

Electron の API ドキュメントは Electron Coding Style と Electron Styleguide に準拠しているため、内容はプログラムで解析できます。

electron-docs-linter は electron/electron レポジトリの新しい開発用依存関係となります。 これは、すべての Markdown ファイルを lint し、スタイルガイドのルールを適用するコマンドラインツールです。 エラーが見つかった場合、それらが列挙され、リリースプロセスが停止します。 API ドキュメントが有効な場合、electron-json.api ファイルが作成され、Electron リリースの一部として GitHub にアップロード されます。

Standard Javascript と Standard Markdown​

今年の始め頃に Electron のコードベースが更新され、全 JavaScript で standard リンターが使用されました。 Standard の README は、この決定の後ろ盾である理由の要約です。

Standard スタイルを採用するということは、個人のスタイルよりもコードの明快さとコミュニティの慣習の重要性を高く位置付けるということです。 これはプロジェクトと開発の文化にとって 100% の意義を持たないかもしれませんが、オープンソースは初心者が嫌う場所になることがあるものです。 コントリビューターにしてほしいことを自動化して明確にすれば、プロジェクトがより健全になります。

また、ドキュメント内のすべての JavaScript コードスニペットが有効であり、コードベース自体のスタイルと一貫性があることを確認するために、少し前に standard-markdown を作成しました。

これらのツールを組み合わせて、継続的インテグレーション (CI) がプルリクエストのエラーを自動的に見つけることができます。 これにより、コードをレビューする人間の負担が軽減され、ドキュメントの正確性に関する信頼性が高まります。

コミュニティ活動​

Electron のドキュメントは絶えず改善されており、素晴らしいオープンソースコミュニティがあることに感謝します。 このドキュメントの執筆時点で、約 300 人がドキュメントに貢献しています。

この新しい構造化データで皆さんが何をするのか楽しみです。 考えられる用途は以下の通りです。

• https://electronjs.org/docs/ の改善
• TypeScript を使用したプロジェクトで Electron の開発を効率的にする TypeScript 定義ファイル。
• Dash.app や devdocs.io などの検索可能オフラインドキュメントツール用

今週、electronjs.org にて Electron のドキュメントを掲載しました。 /docs/latest に最新のドキュメントがあります。 古いバージョンのドキュメントも保持します。/docs/vX.XX.XX.X にアクセスすれば、使用バージョンに関するドキュメントも確認できます。

/docs で利用可能なバージョンを確認するか、 /docs/all で最新バージョンのドキュメントを 1 ページに表示できます ( cmd + f 検索しやすい) 。

ドキュメントの内容に貢献したい方は、ドキュメントの取得元である Electron リポジトリ でどうぞ。 マイナーリリースのたびに取得して Jekyll で作られた Electron サイトリポジトリ へ追加します。

どのようにリポジトリから他のリポジトリへドキュメントを移動しているかについて興味があれば、続きを読んでください。 そうでない場合は、 ドキュメント をお楽しみください!

技術的な小話​

私たちは Electron コアリポジトリ内のドキュメントをそのまま保存しています。 これは electron/electron が常に最新版のドキュメントを持つことを意味します。 新しいバージョンの Electron がリリースされるとき、 Electron Web サイトリポジトリ electron/electronjs.org へ複製します。

script/docs​

ドキュメントを取得するために、 スクリプト を、 script/docs vX.XX.X のコマンドラインインターフェースで、 --latest オプション付き及び無しで (取得しようとしているバージョンが最新かどうかによる) 実行します。 私たちの ドキュメントを取得するスクリプト はいくつかのおもしろい Node モジュールを使用します:

• リリースの tarball を取得 して一時ディレクトリへ保存するための nugget 。
• tarball を展開 するための gunzip-maybe 。
• 私たちの Jekyll サイトで動作するよう、 tarball から /docs ディレクトリを ストリーミング して ( through2 の助けを借りずに) ファイルを絞り込み・処理 するための tar-fs (詳細は下にあります) 。

すべて正常に行われたかどうかを テスト が私たちに教えてくれます。

Jekyll​

Electron の Web サイトは Jekyll サイトであり、以下のような構成のドキュメントに Collections 機能を使っています:

electron.atom.io
└── _docs
    ├── latest
    ├── v0.27.0
    ├── v0.26.0
    ├── 続く
    └── さらに続く

フロントマター​

Jekyll が各ページをレンダリングするには、少なくとも空のフロントマターが必要です。 すべてのページでフロントマターを利用するため、 /docs ディレクトリからストリーミングしている間、ファイルが README.md ファイルである (この場合は特定のフロントマター構成を取得します) か、 Markdown の拡張子を持つ他のファイルである (この場合は少し異なるフロントマターを取得します) かを確認します。

各ページは、次のようなフロントマター変数を取得します:

---
version: v0.27.0
category: Tutorial
title: 'クイックスタート'
source_url: 'https://github.com/electron/electron/blob/master/docs/tutorial/quick-start.md'
---

README.md では、 /readme/ とせずに、 index.html の共通なルートを持つ URL を追加の permalink として設定します。

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

構成とリダイレクト​

サイトの _config.yml 内の latest_version 変数は、ドキュメントの取得時に --latest フラグが使われるたびに設定されます。 また、サイトに追加されたすべてのバージョンのリストと、ドキュメントコレクション全体に必要なパーマリンクも追加します。

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

サイトのルートにある latest.md はこのフロントマターを除いて空です。これによって、ユーザはバージョンを指定することなく、ドキュメントの最新バージョンのインデックス (README とも言う) を この URL: electron.atom.io/docs/latest から参照することができます (バージョンを指定することもできます) 。

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

レイアウト​

docs.html のレイアウトテンプレートでは、条件によって情報をヘッダやパンくずリストに表示または非表示しています。

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

利用可能なバージョンを示すページを作成するために、サイトのルートにある versions.md に記されたリストをループします。 また、このページに /docs/ のパーマリンクを与えます。

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

これらの技術的な小話を楽しんでいただけたことを願います! ドキュメントサイトで Jekyll を使用することについての詳しい情報に興味がありましたら、 GitHub ドキュメントチームがどのように公開しているか GitHub's docs on Jekyll をご覧ください。