Sphinx を CloudBees + Bitbucket + GAE で運用

## 目的 今年は情報発信する年と意気込んで、資料公開用のWEBページを作ることにしました。 ## 概要 ツールにはrstで記述できるSphinx を使用。 GAE + Bitbucket + CloudBees を使用するので準備が手間ですが、サービスを使用することでローカル環境で必須のツールはgitとテキストエディタだけ運用できます。 Bitbucket はrstファイルをそのままHTMLで閲覧できるのとソースの管理が充実していて便利です。 CloudBees のGitリポジトリを使用すればさらに手順は短くなりますね。 <br/> <br/> ## 参考にさせていただいた資料 http://ymotongpoo.hatenablog.com/entry/20100320/1269074974 <br/> <br/> ## 環境 ### クラウド環境 - [Google app Engine](https://appengine.google.com/) - [Bitbucket](https://bitbucket.org/) - [CloudBees](http://www.cloudbees.com/) <br/> <br/> ### PCに必要な環境 - インターネット接続 - Python 2.7 - git - テキストエディタ <br/> <br/> ## 作業手順 大まかには以下の流れです。 各種サービスの準備 -> git 環境構築 -> Jenkinsのジョブ作成 -> Jenkins でビルドとデプロイ実行 -> WEB公開 <br/> <br/> ### 1. [GAE] 公開サーバとしてアプリケーションを新規作成 GAEで新規アプリケーションを作成。 ここで設定したApplicationIDはJenkinsの登録で使います。 - ID を 仮に"hoge-docs01"とする <br/> <br/> ### 2. [Bitbucket] sphinxのソースを管理するリポジトリを作成 リポジトリの種類はGit - リポジトリ名 : hoge-docs01-repo <br/> <br/> ### 3. [CloudBees] Jenkins の準備 1. CloudBeesでアカウントを登録 アカウントの登録はサイトの指示に従って登録する。 2. Jenkins で プラグインのインストール Jenkins は CloudBees ログイン後の画面の左上のタブの[Builds]をクリック。 Jenkinsを表示させたら、ジョブででSphinxを資料するためにPythonを実行できるプラグインをインストール。 <div class="note"> プラグインは左ペインから "Jenkinsの管理 > プラグインの管理 > 利用可能タブ" でインストール。 Python が使用できるようになっていればOK。 </div> 3. ジョブの作成とCloudBeesの公開鍵の取得 プラグインは左ペインから "新規ジョブ作成"をクリック。 ジョブ名は任意で、"フリースタイル・プロジェクトのビルド" を選択して OK をクリック。 ジョブが生成されると "CloudBees DEV@cloud Authorization" という欄に公開鍵されているので、Bitbucket のSSH key に登録。 BitbucketのManage Accountを表示するとSSH key があるので、登録する。 ここで、ジョブに最低限の設定を行う。 - ソースコード管理システム -> Git - Repository -> ssh://git@bitbucket.org/{AccountName}/ccm-docs01.git {AccountName} は自分のアカウント文字列に置き換える。 - ビルド・トリガ -> SCMをポーリング // スケジュール -> */15 * * * * - ビルド手順の追加 -> Python builder - Python version => System-CPython-2.7 - Nature => shell - command (以下のコードを貼り付ける) <pre class="brush: shell"> curl -s -o use-python https://repository-cloudbees.forge.cloudbees.com/distributions/ci-addons/python/use-python PYTHON_VERSION=2.7.2 . ./use-python # when using virtualenv, don't forget to source activate! virtualenv -q myenv source ./myenv/bin/activate easy_install sphinx ls cd gaedir/rst make html </pre> - ビルド手順の追加 -> Deploy Python Application for Google App Engine - Application Directory は './' - Application ID は作成したIDを記載 - Version はそのまま 以上で、一旦ジョブの設定は終わり。 ### 4. [Local] 作業ディレクトリを作成 - ディレクトリを作成し、Git の初期化を実行 <pre class="brush: shell"> $ mkdir mysphinx $ cd mysphinx $ git init $ git remote add origin ssh://git@bitbucket.org/{userAccount}/hoge-docs01-repo.git </pre> ### 5. Sphinx 環境を構築 <pre class="brush: shell"> $ curl -O "http://svn.zope.org/*checkout*/zc.buildout/trunk/bootstrap/bootstrap.py" $ python bootstrap.py -d init $ vim conf.py [buildout] parts = py sphinx [py] recipe = zc.recipe.egg interpreter = py eggs = bootstrap [sphinx] recipe = z3c.recipe.scripts eggs = sphinx $./bin/buildout $./bin/sphinx-quickstart </pre> ### 5. GAE 用のコンフィグを作成 <pre class="brush: shell"> $vim app.yaml application: hoge-docs01 version: 1 runtime: python api_version: 1 handlers: - url: (.*)/ static_files: _build/html\1/index.html upload: _build/html(.*)/index.html - url: /(.*) static_files: _build/html/\1 upload: _build/html/(.*) </pre> ### 6. rst で記事を書いて公開 <pre class="brush: shell"> $vim index.rst Welcome to ccm-lulu.com's documentation! ========================================= Contents: .. toctree:: :maxdepth: 2 :numbered: doc001 doc002 Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` $vim doc001.rst Hoge doc ======== hoge01 ---------- - foo - bar hoge02 ----------- - barbar - foofoo </pre> ### 7. Gitリポジトリへpush - 無視ディレクトリを設定 <pre class="brush: shell"> $vim .ignore bin parts eggs $ git add . $ git push origin master </pre> ### 8. Jenkins のビルド、デプロイを確認 CloudBees でgitのpush検知から、sphinx のビルドとGAEへのデプロイをコンソールから確認してください。 ### 9. GAE で公開 GAEの管理コンソールで公開バージョンを指定して完了。 ## 次回、通常の作業方法を記載します。