Sphinxの使い方

SphinxreStructredText(reST) 形式で作成された文書を、PDFやHTML、その他のフォーマットへと変換してくれるドキュメンテーションビルダーというツールです。 Pythonのドキュメント生成のために開発されたものなので、プロジェクトのドキュメント作成にはもってこいです。 また、中身もPythonで書かれているので、へびつかいであれば、ある程度カスタマイズすることもできるはずです。

このKumaROOTSphinxを使って生成しています。 プロジェクト自体はGitHubを使ってバージョン管理をしてあり、ウェブ版はRead the Docsで公開しています。 どういったものか気になる方はぜひKumaROOTのGitHubリポジトリをクローンしてみてください。

はじめたい

ドキュメントのはじめかたや、拡張パッケージの設定方法などを整理しました。

拡張機能したい

僕がよく使う拡張機能を紹介します。

マークアップしたい

ドキュメントをマークアップする方法を整理しました。 Sphinxの基本はディレクティブ(directive)ロール(role)です。

ヒント

ディレクティブロールは、 HTMLだとブロック要素インライン要素、 LaTeXだと環境コマンド、 に相当するイメージで、僕はドキュメントをマークアップしています。

デフォルトの基本はreST(reStructuredText)記法なのですが、 このドキュメントではMyST記法を前提にコードのサンプルを例示します。

HTMLしたい

LaTeX / PDFしたい

ビルドしたい

ドキュメントをビルドする方法を整理しました。

デプロイしたい