マニュアル

SphinxのSCVersioningでバージョンを切り替えられるマニュアルをつくる

SIOS Coati開発チームの清水です。

今回はSphinxについてです。

Sphinxとは「Pythonでかかれたドキュメント作成ツール」で、PythonやAWS CLIのリファレンスもこのSphinxで作成されているので、みたことがある方は多いかもしれません。

ちなみにSIOS CoatiのマニュアルもSphinxで作成されており、過去にブログでも紹介しました。

SIOS Coatiのオンラインマニュアルの作成方法(前編)


Sphinxでアプリケーションのマニュアルを作成したとき、多くの場合はブラウザ上でも見れるようにオンラインマニュアルの形式で公開すると思います。

そのとき、過去のバージョンのマニュアルをどのように公開するかは、結構悩むポイントだと思います。よくあるパターンとしては、ユーザーがいくつかのバージョンの中から選べるようにすることです。

この機能を用意するには、URLを分割したり、ヘッダー/フッターにスイッチを用意したり、バージョンを自動で追跡させたりと、独自で実装するのは割と大変です。Sphinxを利用しているのであれば、Sphinxの機能を活用していきたいところです。

バージョンを選択できるようにするには、readthedocs のようなホスティングサービスを使うのもひとつの手ですが、今回はホスティングサービスなしでもビルドできる SCVersioning を紹介します。

SCVersioning

https://robpol86.github.io/sphinxcontrib-versioning/index.html

SCVersioningは、複数のバージョンを同時にビルドしてくれて、ページ内にしっかりバージョンを切り替えるためのリンクも用意してくれます。
なお注意点として、マニュアルがgitでバージョン管理されている必要があります。その点だけ、ご注意ください。

インストール

公式に記載の通り pip install  するだけです。

pip install sphinxcontrib-versioning

ここで注意があります。この記事公開時点で、SCVersioningは最新バージョンのSphinxに追従できていないようです。

https://github.com/Robpol86/sphinxcontrib-versioning/issues/42

そのため、公式のものを利用する場合は、Sphinxのバージョンをさげて使用してください。

pip install sphinx==1.5.6

なお Pull-Request に、最新のSphinxに追従したものがあるみたいなので、それを使うのも良いかと思います。(動作は未確認です)

https://github.com/Robpol86/sphinxcontrib-versioning/pull/46

使い方

まず ビルドしたいプロジェクト の Makefile がある場所に移動して、次のコマンドを入力してください。

sphinx-versioning build . _build/html

このコマンドを入力することで、カレントディレクトリをビルドして、ファイルを _build/htmlディレクトリに出力します。
なお、デフォルトだと「masterブランチ」をメインページとなり、すべてのブランチ・タグが生成の対象となります。

基本的に作業は以上になります。とても簡単です。あとは 生成されたファイル(_build/html )を自由に移動すれば完了となります。

ビルドオプション

ビルドオプションをつけないと、すべてブランチ・タグでページを生成します。

そのときは  -W "作成対象とするタグ(正規表現)"  のように指定して、生成対象を決めることができます。

その他、詳細は以下のページに記載されている通りに指定してあげると OK です。

https://robpol86.github.io/sphinxcontrib-versioning/v2.2.1/settings.html

よく使いそうなものをピックアップすると、

-w : 生成対象とするブランチを正規表現で制御

-W : 生成対象とするタグを正規表現で制御

-r : メインページとなるブランチ(タグ)を変更

あたりでしょうか。

基本的には、生成対象以外はデフォルトでも十分使用できるかと思います。

まとめ

今回は Sphinx で作成したマニュアルを、バージョンごとに選択できるようにする SCVersioning を紹介しました。

個人的に SCVersioning の開発リポジトリが最近更新されていないところが気になりますが、とても便利です。

ちょっとしたマニュアルを作った際は、ぜひ使用してみてください。

複数のEC2インスタンスに一括でタグをつける

SIOS Coati開発チームの清水です。

今回はEC2インスタンスのタグに関する話題です。

SIOS Coatiでは監視したくないEC2インスタンスに COATI=DISABLEタグ をつけておくことで、監視対象から除外できます。

しかし、たくさんのインスタンスにひとつひとつタグをつけてまわるのは、割と大変です。そこで、今回はリソースグループのタグエディターを使用して、一気にタグをつけたり消したりする方法を紹介します。

続きを読む

SIOS Coatiのオンラインマニュアルの作成方法(後編)

始めに

SIOS Coatiのチームにいる高正(たかしょう)です。
みなさまいかがお過ごしでしょうか。私は先日、夏休みをとって、家族で山梨県に旅行に行ってきました。
昨年も山梨県で今年も山梨県です。特に山梨に所縁はありませんが、去年旅行に行って気に入ったので今年も山梨に赴いた感じです。山梨のおすすめスポット色々あると思いますが、私のおすすめスポットは、ほったらかし温泉です。なんでほったらかし温泉という名前であるかは公式のホームページにお任せしましょう。私がおすすめする理由はただ一つ、景色が良いからです。ここの温泉はあっちの湯、こっちの湯と2つの温泉があります。去年はこっちの湯に入り、今年はあっちの湯に入りました。それぞれ微妙に違いがあって良いです。どのように違うかは実際に行って体験してみたください。ちなみに、天気がよければ富士山がとーってもきれいにみれるビュースポットなのですが、実は私、去年も今年も富士山を拝むことはできていません。いつの日か素敵な富士山を見たいものです。

オンラインマニュアルをデプロイするまでの流れ

前回の記事ではマニュアルの作成はSphinxを使って、マニュアルのデプロイにはBitbucket Pipelinesを使っていると説明しましたが、これらについて具体的などのようなプロセスを経てデプロイされるか説明をしたいと思います。

ざっくりとうちの開発チームにおけるデプロイまでの流れを書くと以下のようになります。

1.reStructuredText(reST)*1で書いたマニュアル用のソースコードを開発用ブランチにコミットする

2.開発用ブランチへのソースコードのコミットを契機にステージング用のS3バケットのマニュアルをデプロイ*2する

3.2のレビューで問題がなければ、本番用ブランチにソースコードをマージしてプロダクション用のS3バケットにマニュアルをデプロイ*2する

*1.reStructuredText(reST)はSphinxで採用されているマークアップ言語です。Markdown記法と似ています。Markdownを理解している方であれば、比較的簡単にreSTを使えると思います。

*2.Bitbucket Pipelinesはざっくりといえば、リポジトリへのコミットを契機に、環境をデプロイするサービスです。現在、SIOS CoatiではBitbucket PipelinesをオンラインマニュアルをS3のデプロイするために利用しています。

利点

ちょいとわかりづらいと思いますが、この流れに共通している名詞にお気づきでしょうか。はい、ソースコードです。この方式の良い点はreSTの書き方さえ抑えてしまえば、製品コードを書くのと同じ感覚でオンラインマニュアルの作成が行える点です。ちなみに、BitbucketがreSTに対応しているのでマニュアルの大まかな確認はBitbucket上で行えます。オンラインマニュアルの構造など、全体の見た目の部分はS3にデプロイされたhtmlファイルを見れば確認できます。

今後の展望

デプロイ作業は今回の記事で説明している方式によりとても簡単になりました。しかし、マニュアルの中身という点では表記揺れがあったり、冗長な表現があったりと改善したい箇所があります。SIOS Coatiでは文章校正は現在、人力でやっています。できれば、これは人力ではなく、ツールで解消したいところです。文章校正のツールとしては、RedPentextlintがあります。今後はこれらのツールを使って、文章校正の手間を極力軽減して、マニュアル作成を楽しく行える環境にしていきたいと思います。

『SIOS Coatiの申し込みから利用開始までのプロセス』更新のお知らせ

こんにちは、SIOS Coatiチームの黒田です。
前回の記事で、『AWS認証方式の変更のお知らせ』を紹介しましたが、AWS認証方式の変更により
『SIOS Coatiの申し込みから利用開始までのプロセス』を更新しましたので、再度、Coatiの申し込みから利用開始までのプロセスをSTEP1~7を紹介したいと思います。

Coatiの申し込みから導入までのプロセス
STEP1 Coatiの申し込み
STEP2 ヘルプデスクアカウントの登録
STEP3 VPC Peeringリクエストの承認
STEP4 ルートテーブルとセキュリティーグループの設定
STEP5 AWSの認証情報の登録
STEP6 監視対象のインスタンスでスクリプト実行
STEP7 Coatiの利用開始

続きを読む

SIOS Coatiのオンラインマニュアルの作成方法(前編)

SIOS Coatiのチームにいる高正(たかしょう)です。
梅雨が開けて夏真っ盛りの今みなさまいかがお過ごしでしょうか。

SIOS CoatiのGA日は2017年2月23日なので、気がつけばリリースから5ヶ月経過したわけですね。早いものです。
その間私は寝起きの腰痛に悩まされ布団からそこそこお値段のするマットレスを買ったり、元気が出ないのでマルチビタミンのサプリに手を出したり、素敵なふんどしを探したり、つまりはなんとか足掻きながら生きていたわけです。

SIOS Coatiをたくさん売れるようにしたい人たちは日々色々な施策を考えています。
いつのまにか、コーティーくんというキャラが気がつけば出来上がり、着ぐるみまで作ってしまうのですもの。
嗚呼なんて素敵なことでしょう。
5月のAWS Summit 2017では企業ブースの対応に駆り出された時に、初めてコーティーくんを見た時の衝撃たるや。

 

 

 

 

 

 

 

 

 

 

 

 

 

 

ブース対応の時に、お客さんの反応が好意的でびっくりしたものです。コーティーくんの女子受けが良いことにとても驚いています。

 

 

 

世の中、何がウケるかわからないものです。コーティーくんの認知度に負けないように私もそれなりに頑張りたいと思います。

ここからはちょっと真面目にTechの話を書きます。

SIOS Coatiは初リリース時はマニュアルをgoogleドキュメントで書いてPDF化してお客様に提供していました。
でもこの方式だと色々と手間があって、開発者が積極的にドキュメントをメンテナンスをしていくモチベーションを持てませんでした。
でもそれが最近、マニュアル作成のツールとプロセスを見直してSIOS Coatiの本体のコードを書くのと同じノリで作業できるようになったんです。

マニュアル作成はSphinxで、マニュアルのデプロイはBitbucket Pipelinesを使いました。

プロセスやツールの変更で楽しく仕事ができるようになるのは良いことです。

今、オンラインマニュアルはこのようになっています。

 

 

 

 

 

 

 

 

 

 

 

 

 

 

さて後編では具体的にどのように変えて作業効率をあげたのかを説明したいと思います!