chore: miseとuvでPython環境を管理するための設定ファイルを追加

.github/workflows/deploy.yml

@@ -15,13 +15,10 @@ jobs:
         with:
           toolchain: '1.77'
       - uses: Swatinem/rust-cache@v2
-      # python3 and package jinja2
-      - uses: actions/setup-python@v2
-        with:
-          python-version: 3.x
-      - run: python3 -m pip install jinja2 PyYAML
-      - run: cargo test --package typst-docs --lib -- tests::test_docs --exact --nocapture
-      - run: python3 ./gen.py
+      - uses: jdx/mise-action@v2
+      - run: uv sync --locked
+      - run: mise run generate-docs
+      - run: mise run generate-web
       # deploy ./dist to https://github.com/typst-doc-cn/typst-doc-cn.github.io
       - name: Deploy
         if: github.ref == 'refs/heads/main'

.mise.toml

@@ -0,0 +1,24 @@
+[tools]
+# python is managed by .python-version
+uv = "0.5.1"
+
+[env]
+_.python.venv = { path = ".venv", create = true }
+
+[settings]
+yes = true
+
+[tasks.generate-docs]
+run = "cargo test --package typst-docs --lib -- tests::test_docs --exact --nocapture"
+
+[tasks.generate-web]
+run = "uv run gen.py"
+
+[tasks.generate]
+run = [
+    "mise run generate-docs",
+    "mise run generate-web"
+]
+
+[tasks.preview]
+run = "uv run -m http.server -d dist"

.python-version

@@ -0,0 +1 @@
+3.12.7

CONTRIBUTING.md

@@ -34,21 +34,109 @@ Typst日本語ドキュメント翻訳プロジェクトにご興味をお持ち
 
 [中国語版](https://github.com/typst-doc-cn/typst-doc-cn.github.io?tab=readme-ov-file#%E6%8A%80%E6%9C%AF%E7%BB%86%E8%8A%82)を参照してください。
 
-### ローカル環境でドキュメントを生成する
+### ローカル環境でWebページを生成する
 
-変更したMarkdown/YAMLファイルから、ローカル環境でWebサイトのデータを生成することも可能です。翻訳の際にこの作業は必須ではありませんが、書き換えたファイルがWebページとして正しく表示されるのか確認するのに役立ちます。
+当プロジェクトは[typst/typst](https://github.com/typst/typst/)の派生リポジトリであり、Webページを生成するためにはRustが必要です。導入していない場合は、[Install Rust - Rust Programming Language](https://www.rust-lang.org/tools/install)に従ってインストールしてください。
 
-まず、このリポジトリのクローンを作成し、`cargo`ツールチェーン、PythonおよびPythonパッケージの`jinja2`と`pyyaml`をインストールする必要があります。
+また、当プロジェクトが独自に導入しているRustを除く開発ツールおよびコマンドは[mise](https://mise.jdx.dev/)で一元管理しています。導入していない場合は、[Getting Started | mise-en-place](https://mise.jdx.dev/getting-started.html)に従ってインストールしてください。
+
+#### TL;DR
+
+> [!NOTE]
+> こちらの説明は要約版です。詳細を知りたい場合は、次以降の見出しを参照してください。
+
+当プロジェクトのルートディレクトリに移動し、以下のコマンドを実行します。このコマンドは初回のみ実行する必要があります。
+
+```sh
+mise trust
+mise install
+```
+
+Webサイトを再生成するには、以下のコマンドを実行します。
+
+```sh
+mise run generate
+```
+
+Webサイトをローカルサーバーでプレビューするには、以下のコマンドを実行します。
+
+```sh
+mise run preview
 ```
-# `./docs`以下のディレクトリを変更した場合は、次の2行のコマンドを実行する必要があります
-cargo test --package typst-docs --lib -- tests::test_docs --exact --nocapture
-# `./docs/i18n`ディレクトリのみを変更した場合は、このコマンド行を実行するだけで済みます
-python ./gen.py
+
+#### miseによる開発環境のセットアップ
+
+> [!NOTE]
+> 以下の内容はmise v2024.11.5に基づいています。内容の不備を発見した場合は、Issueを立ててください。
+
+miseが導入されている環境で初めて当プロジェクトのルートディレクトリに移動すると、以下のように構成ファイルを信頼することを求められます。
+
+```plaintext
+mise ERROR Config file /path/to/typst-jp.github.io/.mise.toml is not trusted.
+Trust it with `mise trust`.
+mise ERROR Run with --verbose or MISE_VERBOSE=1 for more information
+```
+
+この場合は、指示に従って`mise trust`を実行してください。`mise trust`の詳細は、[mise trust | mise-en-place](https://mise.jdx.dev/cli/trust.html)を参照してください。
+
+```sh
+mise trust
+```
+
+miseの設定ファイルでPythonのvirtualenvの自動アクティベートを有効にしていますが、この時点では`.venv/`ディレクトリが作成されていないため、WARNが発生するはずです。
+
+```plaintext
+mise trusted /path/to/typst-jp.github.io/.mise.toml
+mise WARN  no venv found at: /path/to/typst-jp.github.io/.venv
+
+To create a virtualenv manually, run:
+python -m venv /path/to/typst-jp.github.io/.venv
+```
+
+次に、`mise install`を実行して、miseで管理されているツールをインストールおよびアクティベートします。
+
+```sh
+mise install
+```
+
+#### TypstのソースコードからドキュメントデータのJSONファイルを生成する
+
+ドキュメントデータのJSONファイルは、typst-docsによりTypstのソースコード内のコメントおよび`docs/`にあるMarkdownファイル群から生成されます。
+
+`mise run generate-docs`を実行すると、ドキュメントデータのJSONファイルが`assets/docs.json`に生成されます。
+
+```sh
+mise run generate-docs
+```
+
+#### ドキュメントデータのJSONファイルからWebサイトを生成する
+
+Webサイトの生成にはPythonとJinja2を使用しています。また、パッケージ管理にuvを使用しています。
+
+`mise run generate-web`を実行すると、`assets/docs.json`を基にWebサイトのデータが`dist/`に生成されます。
+
+```sh
+mise run generate-web
+```
+
+生成されたWebサイトをプレビューするには、`mise run preview`を実行します。
+
+```sh
+mise run preview
+```
+
+#### Webサイトの生成までを一括で行う
+
+`mise run generate`を実行すると、`generate-docs`および`generate-web`を一括で実行します。
+
+```sh
+mise run generate
 ```
 
-最終的にコンパイルされたファイルは`./dist`に出力されます。
+#### Dev Containerについて
 
-Node.jsがインストールされている場合は、`npx serve ./dist`でプレビューできます。
+> [!WARNING]
+> Dev Containerは現在miseに対応していません。そのため、Dev Containerを使用する場合は、`.mise.toml`を参考に手動で上記の手順を実行してください。
 
 上記のローカル環境を構築するDockerfileも整備しております。詳細は[.devcontainer/README.md](.devcontainer/README.md)をご参照ください。
 

pyproject.toml

@@ -0,0 +1,10 @@
+[project]
+name = "typst-jp-github-io"
+version = "0.1.0"
+description = "Typst documents japanese translation project"
+readme = "README.md"
+requires-python = ">=3.12.7"
+dependencies = [
+    "jinja2>=3.1.4",
+    "pyyaml>=6.0.2",
+]