Sphinxでドキュメントを作成するときの個人的な初期設定をまとめておく。
python製のSphinxというドキュメントを作成するためのツールがある。
多機能で様々なフォーマットをサポートしており、まとまったフォーマットのファイル形式に対応している。
GitHub - sphinx-doc/sphinx: Main repository for the Sphinx documentation builder
最近はこれを使ってまとまった文章を管理している。
ただ、デフォルトのままだとMarkdownの入力が扱えなかったり、使いたいテーマが入っていなかったりする。
いつも同じような初期設定をシているので、共通で行っている初期設定をまとめておく。
まず、以下のコマンドで必要なライブラリを入れる。
$ pip install sphinx recommonmark sphinx_rtd_theme
入れているのは、sphinx本体とmarkdown形式を扱えるようにするrecommonmark、よく使うテーマであるsphinx_rtd_theme。
これらを入れたら、sphinx-quickstartを実行してプロジェクトを作る。
完了したらconf.pyという設定ファイルができているので、以下のように記述する。
$ diff conf.py conf.py.backup 50,54c50,51 < source_suffix = ['.rst', '.md'] < # source_suffix = '.rst' < source_parsers = { < '.md': 'recommonmark.parser.CommonMarkParser', < } --- > # source_suffix = ['.rst', '.md'] > source_suffix = '.rst' 80,81c77 < #html_theme = 'alabaster' < html_theme = 'sphinx_rtd_theme' --- > html_theme = 'alabaster'
md拡張子のファイルを見つけたらrecommonmarkの機能を使ってパースための設定が前半に書かれている。
html_themeを変更するとビルドしたドキュメントのテーマが変わるので、ここに先程インストールしたsphinx_rtd_themeを指定する。
以上で設定の変更は完了。
あとは文章を作り、make htmlとすればhtml形式でビルドしてくれる。
今回の設定以外にも詳細に項目が分かれているので、詳しくは公式のドキュメントを参照したほうが良い。
