コンテンツにスキップ

建築文書

BeeWareのドキュメントに変更を加える前に、既存のドキュメントをビルドできることを確認しておくことが有用です。

ドキュメントを作成する前に、開発環境をセットアップしてください。

Python 3.13 インタプリタがインストールされ、パス上で利用可能であることが必須です（つまり、python3.13 は Python 3.13 インタプリタを起動する必要があります）。

BeeWare はドキュメント作成に tox を使用します。以下の tox コマンドは、プロジェクトのルートディレクトリにある tox.ini ファイルと同じ場所から実行する必要があります。

ライブドキュメントプレビュー

ドキュメントの迅速な編集をサポートするため、BeeWareには「ライブプレビュー」モードが備わっています。

ライブプレビューは警告付きでビルドされます！

ライブサーブはドキュメント更新の反復作業に利用可能です。更新作業中にマークアップの問題が発生する可能性があります。WARNINGで囲まれた問題は標準ビルドを失敗させますが、ライブサーブはコンソール出力に警告を表示しつつビルドを継続するよう設定されています。これにより、ライブプレビューを再起動せずに反復作業が可能です。

WARNING は ERROR とは異なります。ERROR とみなされる問題が発生した場合、ライブサーバーは失敗し、再起動が必要となります。WARNING の問題が解決されるまで、サーバーは再起動しません。

ライブサーバーを起動するには：

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

(venv) C:\...>tox -e docs-live

これにより、ドキュメントがビルドされ、ドキュメントを提供するWebサーバーが起動され、ドキュメントソースの変更をファイルシステムで監視します。

サーバーが起動すると、コンソール出力に以下のような内容が表示されます：

INFO    -  [11:18:51] Serving on http://127.0.0.1:8000/

ブラウザを開き、提供されたURLにアクセスしてください。これでドキュメントの反復作業を開始できます。変更が検出されると、ドキュメントが再構築され、変更されたページを表示しているブラウザは自動的に更新されます。

docs-liveは最初のステップです

docs-liveを実行してライブサーバーと連携するのは初期段階の反復作業を目的としています。プルリクエストを送信する前には必ずローカルビルドを実行してください。

ローカルビルド

反復処理が完了したら、ドキュメントのローカルビルドを実行する必要があります。このビルドプロセスは、マークアップに問題がある場合に失敗するよう設計されています。これにより、ライブサーバーでは見逃していた可能性のある問題を検出できます。

ローカルビルドの生成

ローカルビルドを生成するには：

(venv) $ tox -e docs

(venv) $ tox -e docs

(venv) C:\...>tox -e docs

このビルドの出力は、プロジェクトのルートディレクトリにある _build ディレクトリに配置されます。

ローカル翻訳ビルドの生成

BeeWare'sのドキュメントは複数言語に翻訳されています。英語版ドキュメントの更新は、他の言語版ビルドに問題を引き起こす可能性があります。プルリクエストを送信する前に、すべてのビルドが正常に動作することを確認することが重要です。

利用可能なすべての翻訳のビルドを生成するには：

(venv) $ tox -e docs-all

(venv) $ tox -e docs-all

(venv) C:\...>tox -e docs-all

各言語ビルドの出力は、関連付けられた_build/html/<languagecode>ディレクトリに配置されます。ここで<languagecode>は、特定の言語に関連付けられた2文字または5文字の言語コードです（例：フランス語はfr、イタリア語はitなど）。

単一のビルドに問題が見つかった場合、tox -e docs-<languagecode> を実行することでその個別のビルドを単独で実行できます。例えば、フランス語のドキュメントのみをビルドするには、以下を実行します：

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

(venv) C:\...>tox -e docs-fr

単一言語ビルドの出力は _build ディレクトリに配置されます。

ドキュメントのリンティング

ビルドプロセスではMarkdownの問題を検出しますが、BeeWareはスタイルや書式に関する追加チェック（いわゆる「リンティング」）を実行します。リンティングチェックを実行するには：

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

(venv) C:\...>tox -e docs-lint

これにより、ドキュメントに以下の内容が含まれていないことが検証されます：

  • 無効なハイパーリンク
  • 誤字

単語の正しい綴りが誤りとして検出された場合、その単語をdocs/spelling_wordlist内のリストに追加してください。これにより、その単語がスペルチェッカーの辞書に追加されます。このリストに追加する際は、以下の点に注意してください：

  • 米国式スペルを優先しますが、プログラミング特有の慣用表現（例：「apps」）や名詞の動詞化（例：「scrollable」）については一部例外を認めます。
  • 製品名への言及は、製品が推奨する大文字表記を使用してください（例：「macOS」、「GTK」、「pytest」、「Pygame」、「PyScript」）。
  • ある用語が「暗号として」使用されている場合、辞書に追加するのではなく、リテラル（like this）として引用すべきである。

ドキュメントのビルドが成功したら、ドキュメントの作成の準備が整います。