Sphinx 開発合宿をしました。

去年 に引き続き、開発合宿に行ってきました。

当日や流れや施設の様子など、詳しいところは他の参加者の記事に譲ります。

scrapbox.io

takuan-osho.hatenablog.com

感想

事前にぼんやりと予定していたミッションはだいたい解決しました。

  • ちょっとしたユーティリティ実装についてレビュー & 議論 (テストとか)
    • subprocess.run() が便利
    • appveyor というか windows のテスト周りの見直し
    • イシューテンプレートの見直し
  • Sphinx のパッケージ分割について議論
    • websupport は完全に切り離しが可能に
    • jsmath は分割しました
  • 2.0 のリリースに向けた議論
    • ブランチや deprecation まわりのポリシーを更新
    • 2.0 のリリーススケジュールの提案
    • 今後のリリースサイクルの検討

また、 @takuan_osho の成果として、websupport パッケージの構造の整理をしてもらったのも助かりました。
やってもらったことも嬉しいのですが、色んな人にメンテナンスを手伝ってもらえること自体が非常にありがたいことです。

欲を言えば 2.0 のリリースに向けた残タスクの整理ができると良かったのですが、そこまでは手が回りませんでした。
チケットのトリアージとかね。
そこは普段の開発の中で、引き続きやっていくことにしましょう。

施設の話

今回は国立女性教育会館の予約が取れなかったので みんなのスペース Tsuu を利用しました。

  • 民泊的なやつ
  • 都心から近い (新宿から 1〜1.5時間)
  • 安い
    • 貸し切りで一室まるごとでおおよそ 28,000円ぐらい (税、サービス料込み)
      • 今回は 2泊したので 56,700円
      • ベッドは8台あるので、人数を増やすほどお得!
        • 布団を借りて雑魚寝もできるみたい
  • 設備はいろいろ揃ってる
    • WiFi はバッチリ
    • 人数が多い場合は電源タップを持ち込んだほうがよさそう
      • 4人の場合は備え付けのものでちょうど足りました
    • プロジェクタあり
      • VGA or mini-display-port 以外は変換アダプタが必要
      • HDMI の変換がなかったので、もってきた chromecast は出番がなかった
    • 適当な BGM を流せるように bluetooth スピーカーとかあると良かったかも
    • 予約サイトだとタオルなどのアメニティがないと書いてあったが、提供されてた
      • 歯ブラシ、ひげそり、パジャマなどは持ち込みが必要
  • 小田原駅周辺はそこそこ栄えているのでご飯もお酒も揃ってる
    • 駅前の ぐいのみオハシ というお店が美味しいし非常によかった!
    • 国立女性教育会館と比べるとちょっと誘惑が多いかも?
    • 駅前までは歩いて 15分ほどなので、ぱっと食事を済ませるには遠いかな
    • コンビニまで徒歩数分なので、朝食とかはそっちで買い込んで済ませてました
  • リビングがそのまま開発ルームになる
    • 会議室などを借りるのに比べて、移動しなくてよいのは集中できて良い
    • 時間制限もないので、ご飯を食べに行くとき以外はずっと開発できる (だらけてもよい)
    • シャワーを浴びてきて、またコード書きに戻ってきたりとか。


かなり満足度は高めでした。開発合宿の拠点には申し分ないです。リピありです!

個人スポンサー

今回は 個人スポンサーで頂いたお金 を使って開発合宿に参加しました。
余剰金があったので、他の人の費用も一部負担しています。全体の半額を個人スポンサーから支払い、残りをみんなで負担することにしました。
(全部支払うことも考えたのだけど、ちょっと悩んで僕のためにいくらか残すことにしました)

開発合宿が負担なく実施できているのはみなさんのおかげです。
いつもありがとうございます!

まとめ

今回の宿は非常に満足度が高かったです。
相談したいことや進めたいことが形になったので、プロジェクトとしても成果がでているはずです。
3月にリリース予定の 2.0 に向けて、新年のいいスタートを切ることができました。

2018年を振り返る / 2019年の抱負

あけましておめでとうございます。今年も毎年恒例の抱負エントリからはじめましょう。
年末から年始にかけて、すこし体調を崩していたので休息を兼ねて寝正月です。

さて、三が日も過ぎようとしていますし、ぼちぼち去年を振り返ることにしましょう。

2018年の抱負 として挙げたのは

  • Sphinx のメンテナ活動をがんばる
  • なにか使えるツールをリリースする (少なくとも一本以上)
  • 技術書を読み続ける。時間を取る。
  • 家の片付け
  • 健康生活

の5個でした。

それぞれについて振り返ってみましょう。

Sphinx のメンテナ活動をがんばる:○

917コミット。がんばりました。
f:id:tk0miya:20190103141119p:plain

ちなみに、執筆時点ではあと 450コミット強で作者(Georg)のコミット数を越えられそうです。
コミット数はコードの価値や品質とは直接関係はないのですが、継続的な活動をしているという意味でたまに見ているので、
それが大台に乗るというのは励みになりますね。
ま、最近はリファクタリングで細かいコミットを積みまくってるので、越えられたとしても浮ついたりせずにやっていくことにしましょう。

イシューの数も去年の12月からずいぶん減らしました。開発合宿をやったのも効いてる気がします。
f:id:tk0miya:20190103144532p:plain
今は一進一退な状況ですが、引き続きマイペースにやっていきます。

なにか使えるツールをリリースする (少なくとも一本以上):○

docutils-stubs をリリースしました。
詳細は改めて記事を書くつもりですが、docutils の型情報パッケージです。
1年以上前から仕込んでいたのですが、 @cocoatomo の協力によって完成しました (というか大部分書いてもらった)。

これによって、ついに Sphinx の型アノテーションPython3 ベースに切り替わりました

とてもニッチで、万人にとって使えるものではないのですが、
Sphinx の開発にとっては必要不可欠なものだったので満足度は高いです。

ちなみに、去年「少なくとも pycmark をリリースするというのはやりたい」と書いていたにもかかわらず、
pycmark はノータッチです。おおよそパーサが完成してしまったので、興味がかなり薄れてしまいましたね。あらら。

技術書を読み続ける。時間を取る。:○

今年は Book-a-thon を自宅周辺開催にしたので、何を読んだのかの記録がほぼありません。
ただ、安定して毎月時間は確保していたので、○にしておこうかしら、と。

何人かからは復活? のリクエストを貰っているし、様子を見て外でもやろうと思っています。
興味がある人は声をかけてください。

家の片付け:✗

ごめんなさい、ごめんなさい、ごめんなさい。(2年連続)

健康生活:○

おおよそ安定してました。
疲れが溜まったり、肩や首がばっきばきになることもあるので、
それなりにメンテしていかないとあかんなーとは思ってます (が何もしてない)。

その他の振り返り

個人スポンサー制度をはじめました

このブログや Twitter でも何度か宣伝をしていますが、今年から個人スポンサー制度を始めました。
おかげさまでたくさんの方に支援していただき、安心して喫茶店開発を続けられています。
また、mac mini を刷新したのでそれもぼちぼち活用していこうと思っています。

技術書典で docutils 本を出した

おそらく世界で唯一の docutils 本です。
スケジュールの都合から突貫でかきあげたものなので、続きを書く時間を取りたいですね。

CTO になった

弊社(株式会社タイムインターメディア)の CTO に就任しました。
…が、目の前の仕事に追われてしまい、CTO っぽいことはほとんどできていません。
半年かけてやることが徐々に見えてきたので、来年も目の前の仕事と取っ組み合いをしつつ、
うまく時間を作って付き合っていこうと思います。

まとめ / 2019年の抱負

去年の抱負の成果は ○ 4つ、× 1つでした。割と達成できてますね。
ただ、体感としては進歩した気がしないので、慢心せずやっていくとしましょう。

というわけで、さっくり今年の抱負。

  • Sphinx のメンテナ活動をがんばる
    • 引き続き。今年は 2.0 出すぞ!
  • なにか使えるツールをリリースする (少なくとも一本以上)
    • いつもの
  • 技術書を読み続ける。時間を取る。
    • 引き続き
  • 家の片付け
    • 来年こそ土下座せずに済むようにしたい
  • 新しい技術へのチャレンジ
    • Sphinx ばかりでマンネリなので、なにか新しいことやりたい
    • メンテナ仕事を放り投げるわけにもいかないので、どうやるといいのか考えるところから。

tox-3.2.0 以降で usedevelop を指定しながら、deps に自身を指定するとハマる件

バグを踏み抜きました。

tox-3.2.0 以降で、次のような tox.ini を作っていると、テストを実行してもパッケージが更新されなくなります。

[testenv]
usedevelop = True
deps =
    .[extra]

具体的な条件としては

  • usedevelop を指定している
  • 自身を deps に extra 込みで指定している

のふたつです。

変更点を読み解いていくと、3.2.0 から deps のインストールコマンドが pip install から python -m pip に置き換わったのがきっかけのようです。この変更がなぜ問題を引き起こしているのかまでは追いかけきれませんでした。


この条件を満たすと、tox 内の virtualenv は次のような状況に陥ります。

  • 対象のコードは site-packages 以下にインストールされる
  • tox は usedevelop モードで動作するので、二度目以降は対象コードはインストールされない

そのため、この状態から抜け出すには --recreate (-r) をつけて、環境を作りなさなければなりません。

回避策は以下のいずれか。

1) deps に自身を書かない。extras を指定したい場合は tox.ini に extras 設定を追加する

[testenv]
usedevelop = True
extras = foo,bar,baz

2) install_command オプションに pip install を指定する (旧動作に戻す)

[testenv]
usedevelop = True
deps =
    .[extra]
install_command = pip install {opts} {packages}

3) tox-3.1.3 にバージョンを下げる


お使いの環境やプロジェクトに合わせて適切なものを選ぶと良いでしょう。
ちなみに 1) は tox-2.4 (2016-10-12) 以降向けです。

さて、Sphinx ではどうしようかしら。

Google 図形描画で書いた図を取り込む sphinxcontrib-googledrive をリリースしました。

ひとつ前の記事で書いた『マスタリング docutils』では、作図に Google 図形描画を使いました。

以前は Cacoo を使ったり、Inkscape を使ったりしていたんですが、維持するのにお金が必要だったり、
CI 環境を作るのが面倒くさかったりして、今回は Google 図形描画を使うことにしました。
あまり図が複雑ではなかったのと、手軽に書きたかったというのも、ツール選びに関係していそうです。

執筆中は時間もなかったので、書いた図は手でエクスポートして貼り込んでいましたが、いま振り返ると先にこのツールを作っておけばよかったと思います。
なにせ、図を書き換えるたびに

1. エクスポートして
2. (余計な空白が入るので) ImageMagick でトリミングして
3. リネームして特定の場所に置く

というのを手動で実行する必要があるのです。
『マスタリング docutils』では図は数点しかないものの、執筆に合わせて何度も書き換えていたので、
それに合わせてなんどもこの作業を繰り返していました。
一度二度ならいいのですが、何度もやってるとミスするんですよね、こういうやつ。

さて、もう執筆は終わって時間が取れたということで、やることはひとつです。
我々は技術の子ですから、こういう無駄な作業は自動化する以外に選択肢はありませんね。
ということで、作りました。
github.com

Google DriveAPI を使って画像をダウンロードし、いい感じにトリミングしてくれる Sphinx 拡張です。
しかも、PDF 出力のときはベクターデータで埋め込むようにしています。
(注意: まだ PDF のトリミング処理は実装していません)

これで図形の微調整を繰り返しても安心ですね。
全国の Google Drive 愛好家の皆さんはぜひ使ってみて、意見を貰えるとありがたいです。

おまけ:残念なところ

README ではリンクを貼るだけで説明を端折っていますが、Google Drive API を使うためにいくつかの作業が必要です。

  • Google Cloud Console でプロジェクトを作る
  • Google Drive API を有効にする
  • サービスアカウントを作る

最後のものは OAuth2 で代替できたのですが、CI 環境で扱いづらいのでサービスアカウントを使うことにしました。
公開範囲の管理にも関連するのですが、いまのところはこのやり方で行こうと思ってます。

技術書典5 で『マスタリング docutils』を出版しました

先週末、技術書典5に「マークアップ言語愛好会」というサークルで参加し、『マスタリング docutils』という本を出版しました。
techbookfest.org
techbookfest.org

マスタリング docutils

この本はこんなまえがきからはじまります。

みなさんは docutils をご存知でしょうか。
docutils はふたつの側面を持つソフトウェアです。
ひとつは Python 製のドキュメント処理フレームワークとしての側面。
もうひとつはそのフレームワークの上に実装されたドキュメント変換ツール群としての側面です。


本書では、前者のドキュメント処理フレームワークとしての docutils にスポットを当て、どのような構造をしているのか、
どのような順序で処理が行われるのか、そしてどのように拡張するのかについて紹介します。

Sphinx はこの docutils の上に構築されたツールです。したがって、SphinxSphinx 拡張を作る上で避けては通れません。しかし、残念なことに docutils はドキュメントや解説が少なく、理解がとてもむずかしいという問題があります。
自分が Sphinx の拡張を書き始めたときに、最初につまづいた (そして今も時々つまづく) のがここです。

本書はその問題をカバーすべく、docutils がどのような構造をしているのか、どのようなフローで処理が進むのか、
そしてどこが拡張ポイントなのかというのを紹介したおそらく世界初の docutils 解説書です。

執筆から販売まで

申し込んだ時点から予想はしていたのですが、今回は執筆時間に充てる時間が限られていました。
9月半ばに開催された PyCon JP 2018 での発表資料づくりに手間取ってしまったため、執筆できるようになったのが 2週間前でした。
そこからハイペースに執筆をして仕上げたのが本書です。

執筆期間が短いとボリュームが…という懸念があったものの書き上げてみると 60ページ弱になりましたし、
肝心のクオリティについても、(断腸の思いで一部見送った章があるものの) おおよそまんぞく行くものができました。

普段からよく触って中も覗いている docutils ですが、今回の執筆にあたって改めてこんなことをしています。

  • 歴史を追うために Doc-SIG の投稿を(ピックアップしながら)斜め読みした
  • 経緯を知るために PEP 256-258 をひたすら読んだ
  • 説明のために docutils のコードを読みふけった

ですので、内容についても胸を張ってお見せできるものです。

ひとつ残念だったのは、ギリギリすぎるスケジュールによって印刷に回す時間が取れなかったことですね。
そもそも技術書典に申し込んだゴールのひとつが Sphinx を使って、執筆から出版(印刷)までの過程を体感してみるというものだったので、自分の目標としては未達成でした。残念。

ツール

今回執筆に使ったのはこのあたりのツール / サービスです。

  • Sphinx (執筆、出力)
  • gitlab (CI)
  • Google drawings (画像)
  • slack (オンラインレビュー / 監視)
  • ラクスル (ダウンロードカード印刷)
  • ジョナサン (セルフ缶詰スペース)

反省

Twitter でいろいろ書いたのを貼り付けておきます。









今後の予定

本書をほしいという奇特な方が現れたので、Booth でダウンロード販売をしています。
興味がある方はこちらからどうぞ。

また、ダウンロードカードはまだ余っているので、カードが欲しい人はお声がけください。

大事なこと

本書で docutils に興味を持った人は、実際に docutils フレームワークをフル活用している事例として Sphinx があるので、
ぜひとも一緒に開発しませんか!
Sphinx プロジェクトではいつでも協力者を求めていますよ!

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

ぼちぼち Sphinx-1.8 をリリースしようというこのタイミングで、以前書いた Sphinx コードの半減期と未来予想図 - Hack like a rolling stone を見かけたので、1年半ぶりに試してみました。

将来、また実行したくなったときにさくっと再現できるようにこんな Dockerfile を書きました。全部 RUN で書いてるのでとても雑ですね。

FROM ubuntu:bionic

RUN apt update; apt install -y python3 python3-pip git; apt-get clean
RUN pip3 install git-of-theseus
RUN git clone https://github.com/sphinx-doc/sphinx /sphinx
RUN git-of-theseus-analyze --ignore 'tests/*' /sphinx
RUN git-of-theseus-stack-plot /cohorts.json
RUN git-of-theseus-survival-plot /survival.json
RUN for mod in application builders directives domains environment ext util writers; \
do (cd /sphinx; echo $mod; find sphinx/$mod* -type f -exec git annotate {} \; | perl -ne 'm/(\d+)-\d+-\d+/; print $1, "\n"' | sort | uniq -c; echo); \
done
CMD cp /*.png /mnt

現時点の半減期グラフはこうなりました。なお、今回は tests/ ディレクトリは対象外にしています。
f:id:tk0miya:20180826183051p:plain

徐々にコード規模が増えてきてますね。
5年以上前のコードも徐々に新しいコードに入れ替わっていっています。2010-2012 あたりのコードは完全に虫の息ですね。


もうひとつのグラフは主要モジュールごとの年代比率です。
f:id:tk0miya:20180826164448p:plain
どのモジュールもここ 3年で大きく手が入っていますね。environment などは 75% 以上の書き換えが行われています。
これは行ごとのタイムスタンプから計算しているので、実装が大幅に変わったかどうかはわかりません (typo 修正にも反応する)が、リリースから 10年が経過したいまでもあちこちに手が入っていることがわかります。

ext や writers あたりは比較的古いコードがそのまま残されているようです。
この傾向は自分の感覚とも一致しています。


ところで、以前の記事ではこんなゴールを挙げていました。

  • Sphinx を細かくモジュール分割すること
  • モジュールの結合度を下げること
  • Sphinx 自身を Sphinx API で作ること

自分の感触としては、まだ道半ばという感じです。
クラス変数を使う箇所をかなり削ったり、API やモジュールの責務を整理したりと、一歩ずつ前に進んでいるので引き続き頑張っていきたいところです。

Sphinx 開発進捗報告 (2018.8)

みなさん、お久しぶりです。tk0miya です。

大変多くの方にスポンサーをしていただいたこともあって(参考)、なるべく定期的に進捗を報告したいなと思っていたのですが、ワールドカップを見ている間に今年もあっという間に半分以上過ぎてしまいました。時間が経つのは早いですね。

というわけで、Sphinx の開発進捗報告です。
f:id:tk0miya:20180804194048p:plain
イシューと PR の残数はこんな感じで遷移しています。
多少ジグザグしているものの、今年に入ってからおおよそ右肩上がりで推移していることがわかるかと思います。

片付けた件数はそれぞれイシューが 415件、PR が 526件でした。
それなりにクローズしているのですが、新たに投稿されるものがそれなりにあるということですね。

ちなみに、Sphinx プロジェクトでは久しぶりに新しいメンバーを迎えました。
検索やドキュメントまわりを担当してくれる TimKam です。
僕が不得意な JavaScript まわりをテコ入れしてくれるようなので、非常に期待しています。

さて、Sphinx は 9月にバージョン 1.8 のリリースを予定しています。
続いて来年の春にはいよいよ 2.0 がやってきます。
もともとは定期的なリリースのひとつでしかなかったのですが、古い API の削除や Python 2.7 のサポート終了など、いくつか大きい変更も行われます。

Enjoy documentation!