今日の到達点
Day 6までで、Mermaid簡易エディタにはリアルタイム描画、構文エラー表示、.mmd保存・読込、SVG出力、コードコピー、データ駆動テンプレートがそろいました。しかし、開発した本人のPCで動くだけでは、別のPCで同じツールを再現できるとは限りません。
Day 7では既存コードを作り直さず、README・依存関係・除外ファイルを整備して、第三者が起動手順を追えるMVPにします。MVP（Minimum Viable Product）は、必要最小限の機能を備え、実際に使って検証できる製品の初期形態です。
flowchart LR
A[既存ソース一式] --> B[依存関係を明記]
B --> C[READMEで手順化]
C --> D[別環境でセットアップ]
D --> E[起動と機能確認]今回のゴールは「説明文を書くこと」ではありません。誰が、どのファイルを用意し、何を実行し、どこを確認すればよいかを一つの文書で追跡できる状態にすることです。
再現可能性を四つに分ける
「READMEがあるから再現可能」とは言い切れません。最低限、次の四つを区別します。
| 層 | 確認すること | 典型的な問題 |
|---|---|---|
| ソース | 必要なファイルがそろっている | templates.jsの入れ忘れ |
| Python環境 | PythonとFlaskを導入できる | 別環境にFlaskがない |
| ブラウザ環境 | JavaScriptとMermaidが動く | CDNへ接続できない |
| 操作 | 起動後に期待機能を使える | ボタンのIDやパスが不一致 |
FlaskはPython側で画面を配信し、Mermaid.jsはブラウザ側で図を描きます。Pythonのrequirements.txtだけでは、CDNから読み込むMermaid.jsのバージョンまで管理できません。Python依存関係とフロントエンド依存関係を別々に記録することが大切です。
Day 6までのファイル構成を固定する
ここでは前回までのファイルを変更せず、次の構成を成果物として整理します。
mermaid-editor/
├── app.py
├── requirements.txt
├── README.md ← 今回作成
├── .gitignore ← 今回作成
├── templates/
│ └── index.html
└── static/
├── css/
│ └── style.css
└── js/
├── editor.js
└── templates.jsapp.pyはFlaskのルーティング、index.htmlは2ペインUI、editor.jsは描画と操作、templates.jsはひな形データです。PythonへMermaid描画処理を移したり、Day 6の機能を別実装に置き換えたりしません。
仮想環境の.venv/はPCごとに作り直すものなので、配布するソース一式には含めません。
requirements.txtを確認する
必要なパッケージを区別する
今回のPythonアプリが直接利用する外部パッケージはFlaskです。mermaidはJavaScript側でCDNから読み込んでおり、Pythonのpipではインストールしません。
Day 1で作成したrequirements.txtがある場合は、いきなり上書きせず中身を確認してください。未作成であれば、最小の出発点は次の1行です。
Flaskこれはインストールには使えますが、バージョンが固定されていません。ほかのPCでできるだけ同じ環境を再現したい場合は、Flaskだけを導入した新しい仮想環境でバージョンを確定し、依存パッケージを含む一覧を記録します。
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install Flask
.\.venv\Scripts\python.exe -m pip freeze最後の出力をUTF-8のrequirements.txtに保存します。Windows PowerShell 5.1では>によるリダイレクトの文字コードが異なるため、エディタでUTF-8保存する方法が確実です。表示された実際のバージョンを採用し、記事中の架空のバージョン番号をコピーしないでください。
pip freezeは現在インストールされているパッケージの一覧をrequirements形式で出力します。ただし、厳密な依存解決結果を保証するロックファイルではありません。再現性を高めるにはPythonのバージョンも記録し、別環境で再インストールを試します。
完成版README.mdを作る
READMEに必要な情報
READMEは利用者が最初に読む案内です。機能紹介だけでなく、前提環境、インストール、起動、操作、制約、トラブル対応まで記述します。
以下をプロジェクト直下のREADME.mdへ保存してください。既存のapp.py、index.html、editor.js、templates.jsを残したまま使う手順です。
# Mermaid Editor (MVP)
Flaskで画面を配信し、Mermaid.jsで図を描画するローカル向け簡易エディタです。
## 主な機能
- Mermaidコードの入力とリアルタイムプレビュー
- 構文エラーの表示
- `.mmd`ファイルの保存と読込
- SVGファイルのダウンロード
- Mermaidコードのクリップボードコピー
- フローチャート・シーケンス図・状態遷移図のテンプレート
## 必要な環境
- Python 3.9以上（Flask 3.1系を使用する場合）
- pipとインターネット接続
- ES ModulesとSVGを扱える現行のブラウザ
- Mermaid.js 12系（`editor.js`でCDNから読み込み）
Mermaid.jsのCDN配信にはネットワーク接続が必要です。
クリップボード機能はブラウザのセキュリティ条件に従います。
## ファイル構成
```text
mermaid-editor/
├── app.py
├── requirements.txt
├── README.md
├── .gitignore
├── templates/index.html
├── static/css/style.css
└── static/js/
├── editor.js
└── templates.js
```
## セットアップ：Windows PowerShell
プロジェクトのフォルダで実行します。
```powershell
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m flask --app app run --debug
```
## セットアップ：macOS / Linux
プロジェクトのフォルダで実行します。
```bash
python3 -m venv .venv
./.venv/bin/python -m pip install -r requirements.txt
./.venv/bin/python -m flask --app app run --debug
```
起動後、ブラウザで `http://127.0.0.1:5000/` を開きます。
終了するときはターミナルで `Ctrl+C` を押します。
## 操作方法
1. 左側にMermaidコードを入力します。
2. 右側のプレビューと構文エラー表示を確認します。
3. `Open .mmd` / `Save .mmd`でコードを読み書きします。
4. `Export SVG`で描画済みの図を保存します。
5. `Copy Code`でMermaidコードをコピーします。
6. テンプレートを選ぶと、確認後に入力内容が置き換わります。
## 動作確認
- トップページが表示される。
- Mermaidコードを変更すると図が更新される。
- 構文エラーを修正すると再描画できる。
- `.mmd`を保存し、読み直せる。
- SVGを出力できる。
- コードをコピーできる。
- 3種類のテンプレートを選択できる。
## よくある問題
- `No module named flask`：仮想環境のPythonで依存関係をインストールします。
- `Address already in use`：ポート5000を使う別プロセスを確認します。
- 図が出ない：ブラウザの開発者ツールでCDN読込エラーを確認します。
- コピーできない：localhostで開き、ブラウザの許可条件を確認します。
## 制約と安全上の注意
- 開発用サーバーです。公開環境では使用しません。
- `--debug`はローカル開発時だけ使用します。
- `.mmd`とSVGはブラウザからローカルへダウンロードします。
- ユーザー認証、クラウド保存、自動保存は未実装です。
- Mermaid.jsのCDN指定はメジャーバージョン固定であり、完全なバージョン固定ではありません。
- 不明な出所の図やSVGを扱う際は内容と安全性に注意してください。
## ライセンス
公開・再配布する場合は、コードと依存ライブラリのライセンスを確認し、
プロジェクト自身の利用条件を別途定めてください。仮想環境を「有効化しない」理由
READMEのコマンドは、.venv内のPython実行ファイルを直接指定しています。仮想環境の有効化は必須ではありません。この方法なら、Windows PowerShellのスクリプト実行ポリシーに影響されにくく、どのPythonでFlaskを起動しているかも明確です。
.gitignoreで配布対象を整理する
ソースコードと、PC固有の生成物は分けて管理します。プロジェクト直下に.gitignoreを作り、次を保存します。
.venv/
__pycache__/
*.py[cod]
.pytest_cache/
.env
.env.*
!.env.example
instance/.venv/にはPC固有の実行環境、__pycache__/にはPythonのキャッシュが入ります。.envは秘密情報を含む可能性があるため、公開しない方針にします。反対に、requirements.txtとtemplates.jsは再現に必要なので除外しません。
.gitignoreはGitへ新たに登録しないための規則です。すでに追跡中の秘密情報を消去する仕組みではありません。公開前には履歴も含めて確認してください。
READMEを使って起動を確認する
まず静的な確認を行う
Pythonの構文を確認するには、プロジェクト直下で次を実行します。
python -m py_compile app.py仮想環境のPythonを使うなら、READMEに示した実行ファイルへ読み替えてください。このコマンドは構文を検査しますが、Flaskの起動やブラウザ描画の成功までは保証しません。
新しい環境で手順をなぞる
再現確認の基本は、以前の仮想環境を使い回さないことです。別フォルダへソース一式をコピーし、READMEどおりに仮想環境を作成してrequirements.txtからインストールします。
起動後は次の順に確認します。
- トップページを開ける。
- Mermaidコードを入力して図が表示される。
- 意図的に構文を壊し、エラーから復帰できる。
.mmd保存・読込、SVG出力、コードコピーを確認する。- テンプレートを選び、上書き確認と再描画を確認する。
これらはDay 8の総合テストへ引き継ぐ手動スモークテストです。スモークテストとは、細かな全機能テストの前に、主要機能が大きく壊れていないか短時間で確認する検査です。
再現時によくある失敗
No module named flask
FlaskをインストールしたPythonと、アプリを起動したPythonが異なる可能性があります。.venv内のPythonを直接指定し、同じ実行ファイルでインストールと起動を行います。
ブラウザが真っ白になる
開発者ツールのConsoleとNetworkを確認します。editor.jsがtype="module"で読み込まれているか、templates.jsの相対パスが正しいか、MermaidのCDNへアクセスできるかを確認してください。
requirements.txtはあるのに再現できない
pip freezeを日常利用の大きなPython環境で実行すると、無関係なパッケージまで記録する場合があります。依存関係は新しい仮想環境で最小限から作り直し、実際のインストール結果を保存します。Pythonのバージョン差やOS差によっても結果が変わり得ます。
--debugのまま外部公開してしまう
Flaskの開発用サーバーとデバッガーは本番運用向けではありません。READMEにある--debugは自分のPCで検証するときだけ使用します。外部公開には別の配備設計が必要です。
実務で使えるREADMEの考え方
READMEは「操作説明書」であると同時に、プロジェクトの再現条件を記録した仕様書です。設計計算ツールでも、入力ファイル、計算ロジック、依存ライブラリ、実行コマンド、確認すべき出力を同じ形式で整理できます。
たとえば将来JSONやDBでテンプレートを管理する場合も、READMEの「ファイル構成」「必要な環境」「操作方法」を更新すれば、変更が利用者へ伝わります。一方、READMEに書いたことが実際のコードと食い違えば、その文書は役に立ちません。コード変更時にREADMEも更新する運用を組み込みましょう。
練習問題
練習1：READMEだけで起動する
別の作業フォルダへプロジェクトをコピーし、元の.venv/を使わずREADMEの手順だけで起動してください。
確認観点： 不足ファイルや暗黙の設定がなく、依存関係をインストールしてトップページを開けること。ネットワークが必要な箇所も確認します。
練習2：配布するファイルを選ぶ
.venv/、requirements.txt、templates.js、.envのうち、通常のソース配布に含めるものを選んでください。
解答例： requirements.txtとtemplates.jsを含めます。.venv/は作り直し、.envは秘密情報を含む可能性があるため除外します。
練習3：再現性の不足を見つける
editor.jsがMermaid.jsを@12で読み込んでいる場合、Pythonの依存パッケージを固定するだけで完全に同じ描画結果を保証できるでしょうか。
解答例： できません。@12はメジャーバージョン指定であり、配信されるマイナー・パッチ版が変わる可能性があります。厳密な再現性が必要なら、実際に検証した完全なバージョンを指定し、ブラウザ環境も記録します。
まとめ
Day 7では、Day 6までの実装を維持したまま、README.mdと.gitignoreを追加し、Python・ブラウザ・Mermaid.jsの依存条件を明示しました。動くコードを残すだけでなく、動かし方と制約を残すことがMVPを共有可能な成果物に変えます。
ただし、READMEの記述だけで動作保証はできません。実際に別環境で起動し、主要機能を確認する工程が必要です。Day 8では、機能間の連携を含む総合テストを実施します。
参考資料
- Flask公式ドキュメント：Installation／Quickstart／Development Server
- Python公式ドキュメント：
venvによる仮想環境の作成 - pip公式ドキュメント：
pip freezeとpip install -r - Mermaid公式ドキュメント：Usage（ES ModulesとCDN）
- GitHub公式テンプレート：Python向け
.gitignore
