Jenkins + Warnings Plugin + flake8 で静的解析

ざっとググってもそれっぽい記事が見当たらなかったのでメモを残しておきます。

Jenkins の Warnings Plugin で flake8 の静的解析の結果を集計するには次のように設定します。

flake8 用のパーサーを追加する

Jenkins の管理 > システム設定 ページの コンパイラの警告 セクションで flake8 用のパーサーを追加します。

項目 値
名前 flake8
リンク名 flake8
推移レポート名 flake8
正規表現 (.):(\d+):(\d+): (.)
マッピングスクリプト (下記参照) 
import hudson.plugins.warnings.parser.Warning
import hudson.plugins.analysis.util.model.Priority

String fileName = matcher.group(1);
int lineNumber = Integer.parseInt(matcher.group(2));
String category = null;
String type = "flake8";
String message = matcher.group(4);
Priority priority = null;

if (message.startsWith('E')) {
    category = "pep8 errors";
    priority = Priority.HIGH;
} else if (message.startsWith('W')) {
    category = "pep8 warnings";
    priority = Priority.NORMAL;
} else if (message.startsWith('F')) {
    category = "PyFlakes codes";
    priority = Priority.NORMAL;
} else if (message.startsWith('C9')) {
    category = "McCabe complexity plugin mccabe";
    priority = Priority.LOW;
} else if (message.startsWith('N8')) {
    category = "Naming Conventions plugin pep8-naming";
    priority = Priority.HIGH;
} else {
    category = "Unknown Error";
    priority = Priority.HIGH;
}

return new Warning(fileName, lineNumber, category, type, message, priority);

priority を決めるところは適当に決めたので、導入時にアレンジしてください。

  • E ではじまるエラー(PEP8 Error) は HIGH
  • W ではじまるエラー(PEP8 Warning) は NORMAL
  • F ではじまるエラー (PyFlakes Error) は NORMAL
  • C9 ではじまるエラー (McCabe) は LOW
  • N8 ではじまるエラー (pep8-naming error) は HIGH
  • その他のエラー(未知)は HIGH

プロジェクトの設定で flake8 を呼び出す

シェルの実行 やその他の方法で、いい感じに flake8 コマンドを実行します。

flake8 src/ --max-complexity=12 --exclude=path/to/tests/ > flake8.log || :
cat flake8.log

flake8 でエラーが検出されても、そのまま処理を進めるように || : とかを挟んでいます。 あと、console output を見て何が起きているのか把握するため、ログを cat しています。

  • プロジェクトの設定でコンパイラ警告の集計を設定する

同じくプロジェクトの設定ページで、Warnings plugin の設定を進めます。

項目 値
集計するファイル flake8.log
パーサー flake8

flake8 コマンドの出力結果ファイルと、システム設定で追加したパーサーを指定します。

さらに静的解析の結果で通知を制御するために、 高度な設定で ビルドステータスの閾値 を次のように設定してみました。f:id:tk0miya:20150309163845p:plain

まとめ

flake8 の解析内容によって success と unstable、 failure を切り替えたかったので、 Jenkins を細かく設定してみました。

追記

Warnings Plugin に PR した方がいいかしら、とリポジトリを眺めていたところ、 パッケージに含まれている PEP8 パーサーは既に flake8 に対応しているようです。

上記で登録したスクリプトとの違いは priority の決め方ぐらいです。

  • E ではじまるエラー(PEP8 Error) は HIGH
  • W ではじまるエラー(PEP8 Warning) は HIGH
  • F ではじまるエラー (PyFlakes Error) は HIGH
  • R ではじまるエラー (??) は NORMAL
  • その他のエラー(未知)は LOW

なんだかぞわぞわする…

SphinxCon JP を開催しました

つい先日、SphinxCon JP 2014 が開催されました。
僕は所用があったため、午後の発表と懇親会だけ参加しました。
「Sphinx をはじめよう」というテーマの通り Sphinx 初心者/中級者に向けた発表がメインでしたが、
本家のアップデート報告、事例紹介、拡張、テーマ、おとなりさん紹介と幅広い内容で
(スタッフなのに)いち参加者として楽しませていただきました。

Sphinx 拡張についてまとめました

また、発表者のひとりとして Sphinx 拡張について整理しました。
スライドはこちらです。

まとめた成果についてはこちらで公開しています。
Survey of Sphinx extensions

Sphinx 拡張の整理については、以前からやろうとは思っていたものの
手間を考えるとなかなか踏みだせないテーマだったのでいい機会ではありました。

r_rudi さんの Sphinx 拡張 探訪 2012 の時点では
Sphinx 拡張は 100個以上あるとあったので、ある程度覚悟はしていたのですが、
実際にリストアップすると 230個も拡張が出てきました。
2年の間に随分増えたものです。おかげで骨が折れました…。


実はもう一本、話したいテーマとして markdown と reST を比較して
拡張性と多様性、方言について思うところを話してみたかったのですが、
他のセッションとややネタがかぶってしまっていたのと、
カンファレンスのテーマ(Sphinx をはじめよう)とも少しズレが有るよね、ということで
今回は不採用となっていました。
これはどこかの機会にまとめられるといいなとは思ってます。

これからのドキュメント(ツール)の話をしよう

懇親会で何人かの方と相談しながら、ドキュメント全般について話す場の相談をしていました。

現在、ドキュメント関連のコミュニティはいくつかありますが、個人的な印象ではそれぞれがバラバラに活動しているような気がしています。

例えば Sphinx と Re:VIEW では別のコミュニティとして動いていますし、
翻訳をしている人たちもプロジェクトごとに集まっていることが多いように思います。
マークアップ言語やツール、プログラミング言語や活動内容(出版、翻訳、リファレンスなど)など
それぞれのテーマごとに幾つものグループに分かれてしまっているため、
知識や問題などがお互いにシェアされず、似たような落とし穴にはまったり、
車輪の再発明が繰り返されているような節があります。

翻訳ひとつ取っても、Jekyllrb-ja プロジェクトと Rails Guides プロジェクト、
そして Sphinx プロジェクトでは翻訳に使っているツールがそれぞれ異なっています。
向き不向きもあるので一概には言えませんが、こうした部分でナレッジやツールが共有されると
やりたいことにもっと注力できるようになるかもしれません。

こうしたテーマを話す場として、なんらかのイベントをやろうと画策しています。
まずは 版管理+自動組版 で版や組版について
議論や相互理解が深まると良いなあと考えています。
そして、できればテーマを変えて第二弾、第三弾と広げられると良いなあと思っています。

まとめ

これからもがんばりましょう。

Sphinx-1.3 に numfig っぽい機能を付けた話

このブログでは numfig の闇と向き合う の記事から numfig との取っ組み合いをしていましたが、
ひょんなことから Sphinx 本体の改修を手伝うことになり、
つい先日 Assign numbers to figures, tables and code-blocks というプルリクが本体に取り込まれました。
また、別のプルリクとして Add :numref: role to refer figures, tables and code-blocks by its fignum が送られていて、
ふたつを合わせると numfig の図表番号という考え方が Sphinx 本体にマージされることになります。

Sphinx 拡張を書くのと比べると Sphinx 本体をいじるのはできることが多くなるかわりに、
奔放なコードを書くと禍根を残すことになるので三倍ぐらい丁寧にコードを読むことになりました。


また、他にも code-block にキャプションを振る機能や graphviz 拡張のキャプションまわりの改善など、
toctree や参照まわりに関する改善を積み重ねてきました。
詳しい日付はまだ出ていませんが、Sphinx 1.3のβ版は近日リリースされるとのことです。

論文や書籍を書くなど、numfig に興味を持っているひとは Sphinx 1.3β にチャレンジしてみてください。
conf.py に numfig = True と書くだけで図表番号が採番されるようになります。


リリースを目前にして、マージされたプルリクのリストを見て、頑張ったなあという感慨を抱いたので記録代わりに記事を書いておきます。

visio2img と sphinxcontrib-visio のメンテナーになりました

少し前、インターン生として @yassu がうちの会社に来ていたので、
その際にドキュメント作成に使うツールを作ってもらいました。

visio2img と sphinxcontrib-visio の 2パッケージです。
それぞれ、visio2img は Visio ファイルから画像ファイルを抽出するコマンドラインツール、
sphinxcontrib-visio は Sphinx 文書の中に Visio 画像を埋め込む Sphinx 拡張です。

ネットワークエンジニアを筆頭に Visio を使って画像を作っている方は多いと思いますので、
これらのツールを使ってよりより便利にドキュメントをつくって貰えればと思います。

なお、visio2img は内部で Visio コンポーネントを呼び出しているため、
実行環境には Visio がインストールされている必要があります。

visio2img は Microsoft さんの提供でメンテナンスされています

これらのパッケージのメンテナンスには Visio のライセンスが必要となるため、
ライセンスを持っている僕がパッケージのメンテナとして活動しています。

さて、この僕の持つ Visio のライセンスですが、実は Microsoft さんによって提供されています。
去年の 5月に開催されたカンファレンスカンファレンスで Microsoft さんから頂いたものを使っています。
おかげさまで visio2img のメンテナンスに役立てることができました。

改めて Microsoft さんには感謝したいと思います。

今後の予定

とりあえず、自分が思いつく一通りの機能は実装して一段落したところです。
使っていただいて、気になる点があればレポートをお願いします。

SphinxCon JP を開催することにしました

すでに渋谷では SphinxCon 開催の話題でもちきり状態で、
ご存じない方はもういらっしゃらないとは思いますが、今年も SphinxCon JP 2014 を開催します。

ノリと勢いで 2012, 2013 とやってきていましたが、なんと 3年目を迎えることになりました。
参加者も発表者も募集しているので、興味がある方はお誘い合わせの上登録をお願いします。
今年の状況によっては、2015 の開催につながるかもしれないので、ちょっとでも興味があれば飛び込んでみてください*1。


さて、この SphinxCon JP の開催までは精鋭スタッフの努力によって成り立っています。
今年はそのリーダーとして @usaturn 氏が先頭に立ち、来るイベント当日に向けて準備を進めています。
そこで、今回はリーダー @usaturn 氏のために、新たに Sphinx 拡張を作ってみました*2。
それが sphinxjp.usaturn です。

sphinxjp.usaturn は warning や note などの、admonition と呼ばれるテキストブロックの記述に用います。
sphinxjp.usaturn の設定を行うと usaturn ディレティブが追加され、
reST の中でうさたーんに注意書きをしゃべってもらうことができます。
たとえば

.. usaturn:: こんにちは、私はうさたーんです。

とマークアップを行うと、次のように変換されます。
f:id:tk0miya:20140907111027p:plain

また、sphinxjp.usaturn は add_character_admonition という API を提供しているため、
conf.py で設定を書き加えることでうさたーん以外にも喋らせることができます。

この機能を用いると、キャラクターの対話形式の記事も簡単に作ることができます。

.. usaturn:: こんにちは、私はうさたーんです。

.. shimizukawa:: こんにちは、私はペンです。
   :align: right

.. usaturn:: いいえ、それはペンではありません。久美です。

.. shimizukawa:: ケン、座ってください。
   :align: right

.. usaturn:: 私も寿司が好きです。

f:id:tk0miya:20140907111545p:plain

とっても便利ですね。

まとめ

  • SphinxCon JP 2014 が開催されます。スピーカーも参加者も大募集中です。
  • sphinxjp.usaturn というモジュールを作りました
  • 犯人はこいつです

*1:Sphinx だけではテーマが限られてしまうので、どうせなら次は他のドキュメンテーションツールを混ぜつつ、DocTool Conf みたいに昇華できるといいのではないかとか、妄想はいろいろありますね。他のツールの状況とかも聞いてみたいし！

*2:sphinx-users.jp 界隈では敬意や感謝を表すために Sphinx 拡張を贈り合う習慣があるとかないとか... 参考: sphinxjp.shibukawa, sphinxjp-tk0miya

YAPC::Asia 2014 に行ってきた #yapcasia

相変わらず perl を書いてはいないのだけど、あのお祭り感が大好きなので
今年も YAPC::Asia に行ってきました。

帰り際に HUB で飲んでた時にスポンサーの人に煽られたのでなるはやで書いてます。


いつもは話半分、コード書き半分ぐらいの感じで過ごすのですが、
今回はわりかしまじめに(?)話を聞いて回ってました。

特に興味深かったのがこの辺り。

誰かが楽しそうに発表したり、面白いことをやってたりすると、すごく刺激されますね。
なにか人に話せる面白いことやりたいですね。

ちょうど JSON Schema を触るのを放置していたので、このあたりのことをやれという天啓だったのかもしれません。
ツッコミも飛んできたのでぼちぼち再開しようと思います。


毎回のことながら、YAPC はやる気を充電してくれるすごいイベントですね。
次回にはなにかネタを持っていけるよう精進していこうと思います。


最後に、今回の YAPC で聞いた中で、声に出して読みたいいい言葉をメモっておきます。



only ディレクティブの微妙なうごき

only ディレクティブを組み合わせるとあれこれ微妙な挙動が発生するようです。

最初は toctree と only ディレクティブの組み合わせについて悩んでいたのですが、
他にも only ディレクティブに関わる動きを @shimizukawa に教えてもらったので
合わせて紹介します。


toctree が 2重登録される

only ディレクティブの下に toctree ディレクティブを配置すると、
その toctree が 2重登録されてしまいます。

例えば、次のような reST を書いてみます。

.. index.rst

heading
========

.. toctree::

   sub

.. sub.rst
続きを読む