Sphinx／ドキュメンテーション勉強会の LT 資料 http://aial.connpass.com/event/30989/

1. Flask アプリで Sphinx
ドキュメントを公開する
2016-05-13 Fri.
白ヤギコーポレーション 森本 哲也

2. Shiroyagi.corp. All rights reserved
概要
● Flask
○ Python の WAF の1つ
○ シンプルな Web アプリの開発
○ Blueprints というモジュール機構
● Sphinxドキュメントのデプロイ
○ 実用例: 管理画面内で仕様書を公開

3. Flask

4. Shiroyagi.corp. All rights reserved
Flask に関連する最近の話題
● GitHub 上の Python フレームワークで☆1位
● Pallets プロジェクトに移管？
○ https://www.palletsprojects.com/
○ https://www.palletsprojects.com/blog/hello/
● Flask のメンテナンス状況？
○ 2013-06-14, 0.10.1, https://pypi.python.org/pypi/Flask
○ 2016-05-09, master, https://github.com/pallets/flask/commits/master

5. Shiroyagi.corp. All rights reserved
Flask の設計
● マイクロフレームワークという冠をかぶった重量級設計
○ あちこちで処理をフックできる (feature creep?)
○ シグナル
■ http://flask.pocoo.org/docs/0.10/signals/
○ Request Context
■ http://flask.pocoo.org/docs/0.10/reqcontext/
○ Application Context
■ http://flask.pocoo.org/docs/0.10/appcontext/

6. Shiroyagi.corp. All rights reserved
多彩な Flask Extension
● Flask Extension もいっぱい
○ がんばればそこそこのアプリも作れるよ！でも ...
● @methane: Flaskの闇
○ 「理想は理想であると見抜けない人には
(Flaskを使うのは)難しい」
○ 循環インポート問題を避ける (´・ω・｀)
■ 実際に開発している管理画面アプリの例

7. Sphinxドキュメント
のデプロイ

8. Shiroyagi.corp. All rights reserved
デモ
● 要件: 管理画面内で仕様書を見たい
○ 1つの解: Flask アプリ内に直接埋め込んだ

9. Shiroyagi.corp. All rights reserved
Flask アプリ内にドキュメントディレクトリを作る
● アプリケーションのリポジトリ内に
直接ドキュメントディレクトリを埋め込む
○ git submodule
○ 別のリポジトリを管理する機能
ディレクトリ構成
api_admin/
├── __init__.py
├── apps
│ ├── __init__.py
...
├── doc
│ ├── build
│ └── source
...
Sphinxドキュメント

10. Shiroyagi.corp. All rights reserved
Flask アプリで静的ファイルを扱う
● flask.send_from_directory(directory, filename, **options)
○ send_file() で指定したディレクトリからファイルを送信する
○ 簡単に静的ファイルを公開するセキュアな方法
from flask import send_from_directory
@app.route('/doc/<path:path>')
@login_required
def doc(path):
return send_from_directory(app.config['DOCUMENT_DIR'], path)

11. Shiroyagi.corp. All rights reserved
flask.send_from_directory をもう少し
● 簡単に静的ファイルを公開するセキュアな方法
● Flask の helper.py を読んでみる
○ 絶対パス指定禁止
○ ディレクトリトラバーサル対策

12. Shiroyagi.corp. All rights reserved
まとめ
● Flask のメンテナンスが今後どうなっていくのかに注目
● Flask で Sphinx ドキュメントを公開するのは簡単