このサイトについて¶

このサイトは、公式のPythonドキュメントや他の多くのサイトを作成するために使用されるオープンソースツールであるSphinx（2.4.4）を使用して構築されています。これは非常に成熟した安定したツールであり、特にAPIアイテムを定義し、コードからそれらにリンクするためのサポートがあるという理由で選択されました。

このサイトでは、Read the docsテーマに基づいたカスタムテーマを使用しています。

サイトの検索¶

検索では、指定されたキーワードすべてを含むトピックが返されます。

ヒント

常に「相互作用」や「コンパイル」のような単一の単語を検索することから始めてください。通常、これで関連ドキュメントを見つけるのに十分です。そうでない場合は、追加の用語を追加して検索を絞り込むことができます。

注意

「-」や「+」のような文字を含む検索は機能しません。論理演算子のサポートはありません。

バグの報告¶

Emscriptenの他のバグと同様に、ドキュメントのバグを報告してください。既存のドキュメントを更新するか、新しいドキュメントを作成して修正を支援してください。

サイトへの貢献¶

このサイト（およびEmscriptenの任意の部分）への貢献は大歓迎です！

この記事の残りの部分で、サイトを構築する方法と記事を作成および更新する方法について説明します。

サイトの構築¶

サイトのソースはGitHubに保存されています。編集と追加は、ツールの他の変更と同じようにこのブランチに送信する必要があります。

サイトは、emscripten-core/emscripten-siteのgh-pagesブランチ（GitHub Pages）に公開されています。

注意

公開ビルドのビルドバージョンを更新することを忘れないでください。

Sphinxのインストール¶

このサイトでは、特定のバージョンのSphinxがインストールされている必要があります。次のコマンドを実行して、正しいバージョンがインストールされていることを確認してください。

pip install -r requirements-dev.txt

サイトのビルド¶

サイトは、UbuntuおよびWindowsで、/emscripten/siteディレクトリに移動し、次のコマンドを使用することで、ソースからビルドできます。

make clean
make html

SDKのビルド¶

SDKのビルドは、サイトのビルドとほぼ同じです。主な違いは、SDKのビルドでは、ホームページに、SDKのビルドであることが明確に通知されることです。

SDKのビルドは、sdkbuildタグを有効にすることで有効になります。これは、SPHINXOPTS環境変数を介して行われます。

# Set the sdkbuild tag.
set SPHINXOPTS=-t sdkbuild
make html

# Unset SPHINXOPTS
set SPHINXOPTS=

ビルドバージョン¶

ドキュメントのバージョンは、現在のビルドのEmscriptenバージョンと一致する必要があります。一般的なサイトのビルドの場合、これはEmscriptenバージョンで定義されている最新のタグ付きリリースになります。SDKのビルドの場合は、SDKのEmscriptenバージョンになります。

バージョンとリリース情報は、ドキュメントのいくつかの場所で使用されます。たとえば、著者などです。

バージョン情報はconf.pyで定義されています。変数versionとreleaseを参照してください。これらの変数は、SPHINXOPTS環境変数に新しい値を設定することでオーバーライドできます。たとえば、Windowsのコマンドラインからrelease変数を更新するには、次のようにします。

# Set SPHINXOPTS
set SPHINXOPTS=-D release=6.40
make html

# Unset SPHINXOPTS
set SPHINXOPTS=

記事の作成と更新¶

注意

Sphinxは十分にドキュメント化されています。このセクションでは、このサイトで使用されている特定のスタイルと機能のみを強調することを試みます。

サイトの構築セクションでは、記事のソースを見つけてサイトを構築する方法について説明します。

サイトのコンテンツは、reStructured textを使用して記述されています。構文を理解するには、次の記事を読むことをお勧めします。

reStructured text入門.
Sphinxドメイン（コードアイテムを定義してリンクします）。
インラインマークアップ.

スタイルガイド¶

このセクションでは、著者が一般的なスタイルを使用するのに役立つ、いくつかの非常に簡単な推奨事項を示します。

ヒント

貢献という点では、完璧な文章よりもコーディングとコンテンツの作成をはるかに高く評価しています！最善を尽くして、編集レビューを依頼してください。

スペル：可能な場合は、アメリカ英語のスペルを使用してください。

慣用句を避ける：これらは、非ネイティブスピーカーにとって特に混乱を招く可能性があります（たとえば、「put your foot in your mouth」は実際には「何か恥ずかしいことを言う」という意味です）。

強調

太字：ファイル名、およびUI/メニューの指示（例：「何かをするにはOKを押してください」）に使用します。

斜体：ツール名に使用します - 例：Clang、emcc、Closure Compiler。

等幅フォント：インラインコード（APIリファレンスにリンクできない場合）と、ツールコマンドラインオプションを示すために使用します。

注意

上記のルール以外では、強調を控えめに使用する必要があります。

リスト：必要に応じて、リストの先頭にコロンを使用します。最初の文字を大文字にして、各項目の最後にピリオドを使用します。

ドキュメントまたは見出しへのリンク方法¶

ページにリンクするには、まずページタイトルの前にグローバルに一意な参照（例：_my-page-reference）を定義してから、示すようにrefロールを使用してリンクします。

.. _my-page-reference:

My Page Title
=============

This is the text of the section.

To link to page use either of the options below:
  ref:`my-reference-label` - the link text is the heading name after the reference
  ref:`some text <my-reference-label>` - the link text is "some text"

これは、記事が移動した場合にリンクが壊れないため、：doc：ロールを使用してドキュメントにリンクするよりも優れた方法です。

このアプローチは、サイト内の任意の見出しにリンクする場合にも推奨されます。

注意

コードアイテムへのリンクにはSphinxドメイン、用語集の用語へのリンクには用語など、リンクに役立つ他の多くのロールがあります。

推奨されるセクション/見出しのマークアップ¶

reStructured textは、見出しテキストの後（およびオプションで前）に、句読点文字の別の行を使用してセクション見出しを定義します。文字の行は、見出しと同じ長さ以上である必要があります。例:

A heading
=========

ネストされたセクションを指定するには、異なる句読点文字を使用します。システムでは、ネストされたレベルごとにどの句読点文字を使用するかは義務付けられていませんが、一貫性を持たせることが重要です。推奨される見出しレベルは次のとおりです。

=======================================
Page title (top and bottom bars of "=")
=======================================

Level 1 heading (single bar of "=" below)
=========================================

Level 2 heading (single bar of "-" below)
-----------------------------------------

Level 3 heading (single bar of "+" below)
+++++++++++++++++++++++++++++++++++++++++

Level 4 heading (single bar of "~" below)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Markdownでの作業¶

新しい記事は、ドキュメントセットに含まれる前に、Markdown構文を使用してwikiで作成および議論することができます。これらをrestructured textに変換する最も簡単な方法は、Pandocのようなツールを使用することです。

注意

get_wiki.pyツール（/site/source/get_wiki.py）を使用して、wikiのスナップショットを自動的に取得できます。wikiを複製し、各ファイルでpandocを呼び出します。出力はwiki_staticフォルダーにコピーされます。このツールは、見出し、ファイルが「wikiスナップショット」であるという注意書きも追加し、「インラインコード」としてマークされたリンクをAPIリファレンスの一致するリンクに修正します。

Read the docsテーマ¶

このサイトでは、Read the docsテーマの修正版（これは、/emscripten/site/source/_themes/emscripten_sphinx_rtd_themeのソースにあります）を使用しています。

元のテーマに対する主な変更を以下に示します。

Footer.html
- 著作権がEmscriptenの著者にリンクするように変更されました（一部のコードは翻訳マークアップによって壊れていました）。
- フッターメニューバーを追加しました。
Layout.html
- アイテム付きのヘッダーメニューバーを追加しました。
Breadcrumb.html
- 最初のリンクのテキストを「docs」から「Home」に変更しました。
- 「ページのソースを表示」コードを下部のフッターに移動しました。
theme.css
- サイドバーの目次で4段階の深さをサポートするように変更しました。
- テーマを中央寄せにしました。サイドバーがページの最下部に到達するように絶対位置決めを使用しました。

サイトライセンス¶

このサイトは、Emscriptenの他の部分と同じオープンソースライセンスの下でライセンスされています。サイトへの貢献者は、AUTHORSに自身を追加する必要があります。