Sphinxの使い方
SphinxはreStructredText(reST) 形式で作成された文書を、PDFやHTML、その他のフォーマットへと変換してくれるドキュメンテーションビルダーというツールです。 Pythonのドキュメント生成のために開発されたものなので、プロジェクトのドキュメント作成にはもってこいです。 また、中身もPythonで書かれているので、へびつかいであれば、ある程度カスタマイズすることもできるはずです。
このKumaROOT
もSphinx
を使って生成しています。
プロジェクト自体はGitHubを使ってバージョン管理をしてあり、ウェブ版はRead the Docsで公開しています。
どういったものか気になる方はぜひKumaROOTのGitHubリポジトリをクローンしてみてください。
はじめたい
ドキュメントのはじめかたや、拡張パッケージの設定方法などを整理しました。
拡張機能したい
僕がよく使う拡張機能を紹介します。
マークアップしたい
ドキュメントをマークアップする方法を整理しました。 Sphinxの基本はディレクティブ(directive)とロール(role)です。
ヒント
ディレクティブ/ロールは、 HTMLだとブロック要素/インライン要素、 LaTeXだと環境/コマンド、 に相当するイメージで、僕はドキュメントをマークアップしています。
デフォルトの基本はreST(reStructuredText)記法
なのですが、
このドキュメントではMyST記法を前提にコードのサンプルを例示します。
HTMLしたい
LaTeX / PDFしたい
ビルドしたい
ドキュメントをビルドする方法を整理しました。