2016年を振り返る / 2017年の抱負

あけましておめでとうございます。正月なので、毎年恒例の抱負エントリです。 年末にがーっと連続エントリを投稿したのでもう大体振り返り終わったんじゃないのか、とは思うのですが、それはそれ、これはこれということで振り返っていきます。2016年の抱負 …

Sphinx in 2016

昨日は Markdown の 2016年を振り返りましたが、今日は Sphinx の 2016年を振り返りつつ、 2017年の目標を適当に挙げてみようと思います。 2つのメジャーリリースと 13のマイナーリリース 今年は 1.3.4 から 1.5.1 まで、合計で 15のリリースを行いました。 …

Markdown in 2016

Markdown、あなたのすぐとなりに潜む問題 昨日は toc 拡張の話ついでに、現在の Sphinx と markdown を取り巻く環境について愚痴ったわけですが、Markdown 業界は 2016年のこの時期になっても、いまだに共通的な仕様が決まっていません。2004年、John Gruber…

Sphinx から完全に reStructuredText を追い出した話

いくつかの記事で紹介されているとおり、 recommonmark を使うと Sphinx で markdown を使うことができます。 Software Design 2016年4月号 Markdownで始めるSphinx MarkdownでSphinxできるようになったので試してみた(前編) - 意識の高いLISPマシン Markd…

Sphinx コードの半減期と未来予想図

Twitter で流れてきた コードの半減期とテセウスの船 | 開発手法・プロジェクト管理 | POSTD を読んで、興味深かったのでさっそく Sphinx のコードでも実行してみました。その結果がこちらです。 コードの増え方は時期によって波がありますが、やはり Sphinx…

Linux カーネルでの Sphinx 利用法を見てみよう

年末カウントダウン Sphinx 連載、第3弾です。 一切下準備をせずに連載を始めたので、早くも息切れをしています。 だれかと約束をしたわけでもないのに急にアドベントカレンダー的なものを始めるのは、なんだか死に急いでいる気がしてきました。今回は、今年…

Sphinx のメンテナになって一年が経過した話

クリスマスが過ぎてから始まる Sphinx アドベントカレンダーへようこそ (嘘) Sphinx 大型連載第二夜です。タイトルにある通り、Sphinx のメンテナ活動をして一年が過ぎたので、その話をします。 OSS 開発者のひとつのサンプルケースとして、何かの参考になれ…

Sphinx に mypy の type annotation を導入した話

今年はアドベントカレンダーにも参加していないし、こたつに入ってだらだら過ごそうかと思っていたら、なんか書けと煽られました。年末ですね。@tk0miya qiita の記事まだー?— Tetsuya Morimoto (@t2y) 2016年12月25日何を書こうか思考をめぐらした結果、my…

2014-15年を振り返る / 2016年の抱負

あけましておめでとうございます。2年ぶりの抱負エントリです。 去年は正月の時期を逃してしまい、仕方がないから旧正月に書くことにするか!と思っていたら仕事が忙しくて完全にタイミングを逸してしまいました。2014年の抱負 として挙げたのは blockdiag …

tox で環境変数をセットする方法

先日リリースされた tox-2.0.0 から、コマンドを実行する際に環境変数がフィルタされるようになりました。 (new) introduce environment variable isolation: tox now only passes the PATH and PIP_INDEX_URL variable from the tox invocation environment…

古い pip で --use-wheel を指定してパッケージを入れるとコマンドが生成されないことがある件。

古い pip には wheel まわりの扱いに問題があるようで、 --use-wheel オプションを指定してパッケージを入れたときに コマンドが生成されないことがあるようです。具体的には drone.io の環境に入っている pip-1.4.1 では問題が発生しました。 そのため、 pi…

sphinxcontrib-googleanalytics-0.1 と sphinx-1.3 の組み合わせで Sphinx が落ちる件。

表題の組み合わせだと、こんなエラーを吐いて Sphinx さんが死ぬ。 Traceback (most recent call last): File "/Users/tkomiya/work/blockdiag.com/lib/python2.7/site-packages/sphinx/cmdline.py", line 244, in main opts.warningiserror, opts.tags, opt…

rails-erd でいい感じの ER図を出す

諸事情で ER図をとても作りたくなることってよくありますよね。rails で開発しているプロジェクトだと rails-erd というツールを使うと モデル定義から簡単に ER図っぽいものを生成できるのですが、 なにもオプション指定をしないと複雑で読みづらいものがで…

flake8 で coding: utf-8 の有無をチェックする flake8-coding を作った

# -*- coding: utf-8 -*- というファイルエンコーディングを示す magic comment の有無を lint しようと思ったのだけど 調べてみると Jenkins でやる方法ぐらいしか見当たりませんでした。drone.io やら travis ci やらでサクッとチェックできるように flake…

Jenkins + Warnings Plugin + flake8 で静的解析

ざっとググってもそれっぽい記事が見当たらなかったのでメモを残しておきます。 Jenkins の Warnings Plugin で flake8 の静的解析の結果を集計するには次のように設定します。 flake8 用のパーサーを追加する Jenkins の管理 > システム設定 ページの コン…

SphinxCon JP を開催しました

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

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

このブログでは numfig の闇と向き合う の記事から numfig との取っ組み合いをしていましたが、 ひょんなことから Sphinx 本体の改修を手伝うことになり、 つい先日 Assign numbers to figures, tables and code-blocks というプルリクが本体に取り込まれま…

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

少し前、インターン生として @yassu がうちの会社に来ていたので、 その際にドキュメント作成に使うツールを作ってもらいました。visio2img と sphinxcontrib-visio の 2パッケージです。 それぞれ、visio2img は Visio ファイルから画像ファイルを抽出する…

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

すでに渋谷では SphinxCon 開催の話題でもちきり状態で、 ご存じない方はもういらっしゃらないとは思いますが、今年も SphinxCon JP 2014 を開催します。今年も SphinxCon JP を開催することになりました!10/26(日)です。発表者、参加者の募集を始めたので…

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

相変わらず perl を書いてはいないのだけど、あのお祭り感が大好きなので 今年も YAPC::Asia に行ってきました。帰り際に HUB で飲んでた時にスポンサーの人に煽られたのでなるはやで書いてます。@941 さんにまだブログ書いてない男の人とか…って言われたの…

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

only ディレクティブを組み合わせるとあれこれ微妙な挙動が発生するようです。最初は toctree と only ディレクティブの組み合わせについて悩んでいたのですが、 他にも only ディレクティブに関わる動きを @shimizukawa に教えてもらったので 合わせて紹介…

astah の画像を Sphinx に埋め込む拡張を作ってみた: sphinxcontrib-astah

先々週に cacoo の拡張をつくってそのあとパッケージングもしたのですが、 それに味をしめて(?) UML 系のツールとして名高い astah 向けの拡張もつくってみました。 sphinxcontrib-astah です。やっていることは超シンプルで、内部で astah-command.sh を呼…

あなたの知らない toctree の世界

numfig を実装してやらぁ!と息巻いてコードを書き始めたところ、 シンプルだと思っていた toctree の裏に思わぬ魔境が広がっていて 思わず部屋の隅っこで震えてしまった @tk0miya です。Sphinx のリファレンスを舐めるように読み尽くした toctree マニアに…

Cacoo の画像を Sphinx に埋め込む拡張を作ってみた: sphinxcontrib_cacooimage

今日、こんなツイートをみました。@wataradio blockdiagシリーズか、cacooで作った図をpngで利用ですかねー #sphinxjp— Takayuki Shimizukawa (@shimizukawa) 2014, 8月 12Cacoo で更新した図を Sphinx に貼り付けるにはローカルに保存する必要があります。 …

Sphinx ではどのようにラベルとキャプションを結びつけているのか

Sphinx ではラベル記法と :ref: 記法を使って、 ドキュメントの様々な位置にラベルを張り、それを参照することができます。 .. _target: section --------- セクションへの :ref:`参照 <target>` を作ります。 さて、このとき、ラベルを貼っているのがセクションタイ</target>…

Re: numfig の闇と向き合う

numfig の闇を垣間見るのにも飽きてきたので、これまで見た numfig 系拡張の問題をカバーすべく 自分でも numfig 系拡張を書いてみた。 new_numfig.pyざっくり動かしたところ、うまく動いているようにみえる。既存の fignum 系拡張との違いはこんな感じ。 表…

ファイルを超えてリンクを貼る (domain#resolve_xref() のすゝめ)

昨日の記事で、どの拡張も HTML に変換した時に他のページにリンクできないという体たらくなので、 Sphinx においけるリンクの解決方法をまとめておく。 解決方法: domain#resolve_xref() を使う 以上。 見出しで言い切ったのでこれ以上ネタも無いのだが、コ…

numfig の闇と向き合う

前の記事で あとは numfig の応用で自動採番をすることもできるようになるでしょう。 なんてことを書いてみたのだけど、よく考えてみると一度も numfig を使ったことがなかったので これを機に挑戦してみんとてするなり。 numfig をインストールする numfig …

コード片(code-block)にキャプションをつける

rstのファイルでリストに通し番号を入れる(久々にシェル芸) を見て、"code-block にキャプション付けられなかったっけ?" とおもって調べてみたところ、 Sphinx の code-block ディレクティブも docutils の code ディレクティブもどちらもキャプションをサ…

remarkdown を巡る冒険 (原題: remarkdown versus Sphinx)

docutils はある形式の文書を別の形式に変換するフレームワークです。 このフレームワークを利用して rst2html や rst2latex などが提供されています。しかし、docutils が標準で対応している入力形式は reST 形式に限られているので、 実際には reST 変換用…

flake8 の NOQA コメントは無敵ではない

flake8 のドキュメントを読むと、 警告を抑止する NOQA コメントについて lines that contain a # noqa comment at the end will not issue warnings. (訳: 末尾に # noqa というコメントがある行は警告されません) と説明されています。しかし、実際にはす…

Re: Re: SphinxのLaTeXのフォーマットをいじる

先日、Re: SphinxのLaTeXのフォーマットをいじる の記事を書いた直後に、 sphinx-users ML に独自のclsファイルを使用する方法がポストされました。前回の記事では conf.py でプリアンブル部にゴリゴリ定義を突っ込んでいましたが、 Python の文字列として記…

pandoc + sphinx + transifex で既存ドキュメントの翻訳を行う

この間の Sphinx+翻訳 Hack-a-thon で話題に上がった件について調査してみた。お題は以下のとおり。 元の文書は markdown で記述されている Sphinx を使って翻訳してみようと思っている 元の文書が更新された時に差分管理できるとよい その場で出た案はタイ…

Re: SphinxのLaTeXのフォーマットをいじる

卒論とか修論は TeX で書いていた割には、TeX マクロが苦手な @tk0miya です。 先輩から秘伝のタレ的?なスタイルファイルを頂いたのでそれで済ませてました。Sphinx で PDF 出力するときは TeX を介して出力することが多いのですが、 未だに TeX マクロをち…

Pillow の ImageDraw#textsize() が間違った値を返している件

Pillow 2.2.0 以降には ImageDraw#textsize() にバグがあり、TrueType フォントを指定していると正しい高さが返りません。 どういう問題なのか テキストとそれを囲む四角を描画する次のコードを実行してみます。 from PIL import Image, ImageDraw, ImageFon…

image/figure ディレクティブのオプションまとめ

最近、Sphinx や docutils の blockdiag ディレクティブのオプションを見なおし、 reST 標準の image/figure ディレクティブと同じオプションを受け取るようにしました。 :width: や :height:、:scale: などのオプションが使えるようになっています。その際…

Sphinx 拡張のエラー出力方法まとめ

Sphinx 拡張ではエラーを表示したくなる場面はいくつかある。 設定値が誤っている場合や、環境の設定不足、記述の誤りや通信エラーなど。そんなときに Sphinx/docutils フレームワークを使ってエラーを出力していくのだが、 場面や用途によってエラーの出力…

パーフェクト Ruby のサンプルコードにバグを見っけた。

パーフェクト Ruby の初版、p.486 にバグを見っけた。 公式の正誤表は見当たらなかったので記事にしておく。capistrano の capture 関数のサンプルとしてリスト 14.14 にこんな記述がある。 task :log_size_watcher do log_file = "#{deploy_to}/shared/log/…

detox が依存性の解決に失敗してたまにコケる話

書こう、書こうとおもってさぼってた話を書きます。複数の Python バージョンをサポートするライブラリを作っていると、tox があるとテストがとても楽になります。 ただし、Python のバージョンによって依存するライブラリが変化する場合は、 setup.py と to…

PHP_CodeSniffer-1.5.x と phing-2.6.1 が喧嘩するので phing の開発版を使った話

一度テスト環境を作ったまま、そのままテストを回し続けていた PHP プロジェクトがあるのですが、 composer が Warning: This development build of composer is over 30 days old. It is recommended to update it by running "composer.phar self-update" …

2013年を振り返る / 2014年の抱負

新年早々富士山見てきましたが、超寒かったです。でも、逆さ富士と赤(っぽい)富士を見ることができました :-) さて、2013年もようやく終わったのでちょっとだけ振り返りしてみることにしましょう。2013年の抱負 として挙げたのは ドキュメント系のツール/コ…

2013.12 版 python2.4-3.3 までのテストツール対応状況

ここしばらく python 2.5 に対応した python コードを書いていなかったので気にもとめませんでしたが、 diff-highlight を書くときに python 2.4, 2.5 対応でハマったことについてまとめます。 ちなみに diff-highlight を python 2.4, 2.5 に対応させたのは…

git と mercurial の diff を美しく表示するために必要なたった 1つの設定 (原題: diff-highlight 1.0.0 をリリースしました)

Git の diff を美しく表示するために必要なたった 1 つの設定 #git にインスパイアされて作り始めた diff-highlight にあれこれ手を入れ、1.0.0 として正式リリースしました。 diff-highlight と git-contrib/diff-highlight の違い 差分の中で +/- の行数が…

Python のコードを取り込むときの注意点 (Python のライセンスについて)

hg-diff-highlight を実装するにあたって、difflib.Differ クラスの実装を一部コピーしました。Python のライブラリをコピーして自分のプロダクトに取り込むので、 どのように扱えばいいのかライセンス上問題ないか聞いて & 調べてみました。Python の標準ラ…

difflib の使い方 〜hg-diff-highlight を例にして〜

hg-diff-highlight という Mercurial 拡張を作った話を書いたのですが、 このエントリではその実装について、特に内部で使っている difflib の使い方についてご紹介します。 hg との連携部分 hg-diff-highlight では mercurial の diff 計算部分には手を入れ…

続・Mercurial の diff を美しく表示するために必要なたった 1つの設定

つい一昨日、Mercurial の diff を美しく表示するために必要なたった 1つの設定 という記事を書いたばかりですが、 diff-highlight の動作を見ているといくつか気になるところを見つけてしまいました。 diff-highlight のイケてないところ 差分の中で +/- の…

シェルスクリプトで出力先がターミナルかどうかを判定する

先ほどの記事 でエスケープシーケンスまわりについて調べている時に、 「出力先がターミナル(tty)の場合」と「出力先がファイル、その他の場合」でエスケープシーケンスを出し分けする方法が気になりました。たとえば、ls コマンドでは $ ls --color=auto と…

Mercurial の diff を美しく表示するために必要なたった 1つの設定

このエントリは Mercurial Advent Calendar 2013 の17日目です。 タイトルは Git の diff を美しく表示するために必要なたった 1 つの設定 #git のパクリです。すみません。↑の記事を読んで、単語単位で diff 表示のできる git + diff-highlight が羨ましく…

screen の上で 256色の vim を使う

tmux 使えよって罵倒されそうですが、未だに screen を使っています。 ようやく vim のシンタックスハイライトを有効にして生活し始めたのですが、 開発に使っているさくら VPS に設定を反映したところ 16色モードで動いていると判断されているため jellybea…

vim のシンタックスハイライトと自分なりに付き合う

僕は長らく vim を使っている(おそらく 14,5年)のですが、常にシンタックスハイライトをオフにして使っていました。 オフにしている理由は、特にメリットを感じなかったことと、もうひとつは編集時のハイライトの挙動です。 vim のハイライトは編集モードで…