TIM Labs

tk0miyaによるエントリー一覧

CTOの小宮です。

先月開催された PyCon JP 2020で「How Sphinx generates document from Python code」というテーマで発表してきました。

こんにちは、@tk0miya です。 PyCon JP 2020 プロポーザル採択速報 によると、私が投稿した「Sphinx はどのように Python コードからドキュメントを生成するのか」が今年の PyCon JP 2020 に採択されたようです。ありがたいことです。

予定しているトークの内容は以下のようなものです。

Sphinx は Python の公式ドキュメントや numpy, pandas, django など数多くのプロジェクトで利用されているドキュメント生成ツールです。

Sphinx が広く利用されている理由のひとつに Python プログラムからのドキュメント自動生成(autodoc)があります。ドキュメント自動生成機能を用いると、手元の Python コードからかんたんにドキュメントを生成できます。本セッションではこのドキュメント自動生成機能がどのように実装されているのかにフォーカスを当て、Python プログラムの動的解析および静的解析の実装方法をご紹介します。

発表内容:

  • Sphinx とはなにか
  • Python コードからドキュメントを生成する
  • Python オブジェクトから情報を抽出する (動的解析)
  • Python のスペシャルメソッドを理解する
  • PEP を読む
  • Python コードから情報を抽出する (静的解析)
  • AST の使い方
  • Python のバージョン差と戦う
  • 質疑応答

さて、そんな PyCon JP 2020 ですが、今年はコロナの影響もあってリモートでの開催になることが決定しています。 ですので、このセッションも自宅から発表することになります。 そこで、本記事では PyCon JP 2020 に向けて整えた自宅の収録環境を紹介します。

こんばんは、小宮です。

本当に使ってよかったOpenAPI (Swagger) ツール を見て Stoplight Studio を使ってみたくなったので、homebrew cask に cask を登録してみました。 登録してもらった PR はこれです

これで brew cask install stoplight-studio でインストールできるようになりました。 homebrew-cask に登録されていないパッケージを見つけた場合は、homebrew-cask プロジェクトに PR を投げて cask を追加してもらいましょう。

Cask の作り方

cask を作るには大まかに、以下の 5つのステップを順次に実行していきます。

  • generate_cask_token コマンドによる cask token の生成 (ファイル名などに用いる)
  • brew cask create コマンドで cask コマンドを生成
  • メタデータを書き込む (アプリ名とか URL とかハッシュ値とか)
  • インストール、アンインストールの動作確認
  • 作成した cask ファイルをコミットして PR を投げる

詳細な手順は ドキュメント に非常に丁寧に (ステップごとに) まとめられているので、ここでは詳細は説明しません。 PR のテンプレートでも、各ステップを実施したかのチェックボックスが並んでいるので、ドキュメントを読みながらであればすぐ作れるはずです。

今回は 20分ほどで cask を作りました (1年ぶり2度目)。

まとめ (?)

Stoplight Studio の cask を作ってみました。便利そうなツールなので、ぜひ cask 経由でインストールしてみてください。

弊社小宮が先月開催された PyCon JP 2018で「Sphinx-2.0 とドキュメントの未来」というテーマで発表しました。

弊社 CTO の小宮はプライベートではオープンソースプロジェクト Sphinx の主要メンテナとしても活動しています。

Sphinx のベースになっている reST フォーマットには打ち消し線用の書式がありません。
ですが、お仕事で文書を書いていると「ある仕様がなくなったこと」を示したいことがあるため、
稀に打ち消し線を使いたくなることがあります。

周りの人に聞いてみたところ、テーマをいじる方法や
各 reST におまじないを書く方法などを教えてもらったのですが、
ふとした時に使いたくなっても忘れてしまいそうな印象を受けました。

そこで打ち消し線を簡単に使えるよう、簡単な拡張を作ってみました。
私は iPhone ユーザーなので Android のスクリーンロックはほとんど使ったことがないのだけど、
偶然このブログで Haskell で Android の指リストパターンを数え上げる という記事を読んで、
Python で同様のコードを書いてみようと思いつきました。
ブログのネタが無いので人の褌で相撲をとってやろう、ということです。
ちょっと足を伸ばして yokohama.pm で Sphinx と blockdiag の話をしてきました。

最近自分でも Sphinx + blockdiag の組み合わせで使い始めていて、
このスライドに書いたようなスピードを感じています。
実際に使うと Sphinx が魔法のツールと呼ばれている理由が分かりますよ!

「本当のドキュメントと向き合えますか」というタイトルで qpstudy で話してきました。
3分LT という超短い時間だったので駆け足での発表になりましたが、
インフラエンジニアの方もドキュメントは悩みの種なのか、blockdiag を気に入ってくれた方がいるようです。

また、この発表に合わせて作った netdiag も悪い感触ではなかったようなので、
これから作り込んでいこうかと思います。


これは新卒準備カレンダー 2011春の一記事です。
これから IT 業界に入ってくる人たちに向けて。

「ドキュメント、書いてますか?」というタイトルで Python Hack-a-thon で話をしてきました。
いい機会なので blockdiag の中の話をざっくり書きました。

※ ボリューム多すぎて話しきれませんでした(><

そのときの資料をアップします。

このアーカイブについて

このページには、tk0miyaが最近書いたブログ記事が含まれています。

最近のコンテンツはインデックスページで見られます。過去に書かれたものはアーカイブのページで見られます。

月別 アーカイブ