この文書の編集について

この文書は、GitHub上の以下のリポジトリーで管理しています：

https://github.com/freee/a11y-guidelines

内容の修正、追加、誤字脱字の修正などは、上記リポジトリーのIssuesまたはPull Requestsでお知らせください。

Pull Requestを作製する場合は、まず上記リポジトリーをforkしてください。forkしたリポジトリーで作業用のブランチを作製し、必要な変更を加えた上で、上記リポジトリーのdevelopブランチに対してPull Requestを作成してください。

以下、この文書の編集に関する情報をまとめて記します。

作業環境の準備

必要環境

この文書のソースを処理してHTMLファイルを生成するためには、PythonとGNU Makeが動作する環境が必要です。

手元の開発環境では、Python 3.9.xとGNU Make 4.3で動作を確認しています。

開発環境の構築

まず、forkしたgitリポジトリーをcloneします。このリポジトリーでは、Deque Systems Inc.のaxe-coreのリポジトリーをサブモジュールとして含んでいますので、git clone実行時には、--recursiveオプションを指定してください：

git clone --recursive <リポジトリー・パス>

以後、必要に応じて以下のコマンドを実行してサブモジュールを更新してください：

git submodule update --init --recursive

次に、必要なPythonモジュールをインストールします：

pip install --upgrade -r requirements.txt

HTMLファイルの生成

HTMLファイルの生成のために必要な情報はMakefileに記述されており、GNU Makeが必要です。

リポジトリーのトップ・ディレクトリーで以下を実行してHTMLファイルを生成します：

make html

pythonコマンドをpython3などの別名で実行する必要がある環境では、以下のように実行します：

make PYTHON=python3 html

生成されたHTMLファイルは、ja/build/html以下に日本語版が、en/build/html以下に英語版が出力されます。

ソース・コード

この文書は、Sphinxで処理することを前提に作成しています。全体としてはreStructuredText（reST）で記述していますが、ガイドライン項目とチェック内容、FAQについてはYAMLで記述したファイルをreSTに変換して処理しています。

リポジトリーのルート・ディレクトリーには、以下のディレクトリーがあります。

ja

reSTで記述した日本語版のファイルが含まれています。

en

jaディレクトリー内のファイルを英訳したものが含まれています。なお、未訳のファイルについては、日本語のファイルがそのまま含まれています。

data

yaml

ガイドライン項目とチェック内容、FAQの内容や関連情報を記述したYAMLファイルが含まれています。

json

yamlディレクトリー内のファイルのスキーマ定義と、これらのファイルを処理するために必要なファイルが含まれています。

tools

yaml2rst

必要なreSTファイルを生成するためのスクリプトと関連ファイルが含まれています。元々はYAMLファイルを処理してreSTファイルを出力するためのスクリプトだったのでこのような名前になっていますが、現在はaxe-coreのソース・コードを処理して必要なreSTファイルを出力する機能も追加されています。

vendor

サブモジュールとして参照しているリポジトリーのソース・コードが含まれています。現時点では、axe-coreのソース・コードが含まれています。

yaml2rstの実行

tools/yaml2rst/yaml2rst.pyスクリプトを実行すると、必要なreSTファイルを生成することができます。いくつかのコマンド・ライン・オプションがありますが、手動で実行する場合は以下の2つのオプションが必要です。

--langまたは-lオプション

出力するreSTファイルの言語を指定します。日本語の場合はjaを、英語の場合はenを指定します。

--basedirまたは-bオプション

dataディレクトリーがあるディレクトリーを指定します。このディレクトリー内のYAMLファイルを処理してreSTファイルを出力します。

例えば、リポジトリーのルート・ディレクトリーで以下のように実行すると、日本語版のreSTファイルがja/source/incとja/source/faqの各ディレクトリーに出力されます。

python tools/yaml2rst/yaml2rst.py -l ja -b .

なお、ルート・ディレクトリーでmake htmlを実行すると、このスクリプトの実行も含めて、日本語版、英語版のHTMLを出力するために必要な処理が実行されます。

ファイルの編集

ガイドライン項目、チェック内容とFAQについては、data/yaml以下のYAMLファイルを編集します。これらの内容を含むページを中心に、多くのページはYAMLファイルから生成されたreSTファイルをincludeする構造になっています。

一方、source/explanationsディレクトリーにあるファイルを中心に、基本的にreSTで記述されているファイルもあります。これらのページの修正に当たっては、当該のreSTファイルを編集します。

表記ルール

この文書の日本語部分は、原則として日本翻訳連盟が公開しているJTF日本語標準スタイルガイド(翻訳用）に従って記述しています。リポジトリーのルート・ディレクトリーの.textlintrcに、現在使用しているtextlintのルールが含まれていますが、現時点では不完全な状態です。

英語版の位置づけ

この文書の正式版は日本語版です。現時点で、未訳のページもあり、これらについては日本語版のソースがそのまま含まれている状態になっています。英語版は、日本語版の内容を翻訳したものですが、日本語版の内容と異なる部分がある場合は、日本語版の内容が優先されます。

日本語版の更新に当たっては、なるべく同時に英語版を更新するようにしていますが、日本語版の更新が先行する場合もあります。

また、現時点で、未訳のページもあり、これらについては日本語版のソースがそのまま含まれている状態になっています。今後、順次英訳を進めていく予定です。

なお、英訳版が存在するページに関しては、日本語版のソース・コード中に以下のような記述をすることで、英訳版へのリンクが生成されるようになっています。

.. translated:: true