2022-10-14 –, pyconjp_1
Language: 日本語
Pythonista にとってはおなじみになっているドキュメンテーションツールといえば Sphinx です。
さて、そんな Sphinx を使っていて「こんなことは出来ないかな？」ということは無いでしょうか。
Sphinxは、本体には存在しない機能を自分の手で「拡張」することが出来ます。
このセッションでは、発表者の体験を踏まえて「Sphinxの作り方」を解説するとともに、ライブラリに対する機能拡張を行うための考え方を紹介します。
SphinxはPythonistaにとってはとても縁深いツールの一つとなっています。
Pythonドキュメンテーションのベースとして採用されているだけではなく、Pythonベースのプロダクトを開発するときなどのドキュメント管理をするときにも採用されることがあるでしょう。
さて、"Battery included"なSphinxはそのままでも、ドキュメントに便利な書式やバラエティに富んだテーマが同梱されており、便利に使うことが出来ます。
それでも、たまに「出来ることなら〇〇したい」という場面に出くわすことがあるかもしれません。
そんな場面に対して、Sphinxは「Sphinx拡張」という概念が存在します。
Sphinx拡張はSphinxに新しい機能を組み込むための仕組みですが、Sphinx本体はこのためのAPIなども提供されており、要望の実現を手助けしてくれます。
このセッションでは主にSphinx拡張を作る際に「どう組み込めばいいか」「どんな情報を確認すればいいか」を中心とした実装時の考え方を中心を話します。
また、この考えは「〇〇を拡張したい」というOSS活動パターンに対して、「どのようなアプローチを取ればよいか」を知る助けにもなるでしょう。
セションのアウトライン
- 自己紹介
- 概要
- Sphinxの簡単な紹介
- Sphinxとはなにか
- Sphinx拡張の概要
- Sphinxを拡張する～とある自作拡張を例に～
- 自作拡張の簡単な紹介
- アプローチ：「拡張ポイント」を整理する
- Sphinxにおける拡張の扱いを整理する
- Sphinx内のイベントの呼ばれ方、受け取り方
- 実際にイベントを組み込む
- Sphinx拡張の実装プロセスから、〇〇拡張のアプローチを考える
- OSSに対する拡張を考えた際の抽象論
- Not技術的な話
- まとめ
株式会社ニジボックス所属のソフトウェアエンジニア。
バックエンド寄りの領域を中心にしつつ、海外技術記事の翻訳メディアであるPOSTDの運用などを担当しています。
プライベートでは、主にSphinx拡張/Errbotプラグインといったプラグイン系ライブラリや、CLI/TUIツールなどを好んで作って遊んでます。
代表例のsphinx-revealjsは、SphinxドキュメントとしてReveal.jsによるHTMLプレゼンテーションを可能にする拡張となっています。