ドキュメントシステムを使って何するの
私が現在使っている開発ツールなどで日本語ドキュメントが存在しないものがあります。それらを少しずつローカライズしたり、自分用・公開用にまとめたりすることができればと思い、ドキュメントツールについて調べ始めました。もし、よいコンテンツが出来れば販売もできるといいなという思惑もあります。いづれにせよ、アウトライナーよりは、もう少し複雑なことが出来るものを求めています。Wordじゃだめなのか？といわれれば、おそらくそれでも大丈夫だと思いますが、プレーンテキストで入力できることに価値を置きます。そうすることで一括変換や、スクリプトによる操作が可能になるからです。また、文中のソースコードなどをリンクで埋め込み、その指示もテキストで可能。これらのツールを使いこなすことが出来るようになれば、共同でのドキュメント作成にも応用が効くようになるでしょう。
たくさんのドキュメントシステムの中から
ドキュメントシステムには沢山の選択肢があります。用途に応じて選ぶ必要がありますが、これらツールもエディタと同じで学習曲線の違いがあり、長期的に継続的に使っていくなら多少敷居が高くても覚えていく価値はあります。一般的にはDTP用のInDesignなどを想像されるかもしれませんが、今回はそれ以前の文章を積み上げて管理していくツールです。また、出力先としてHTMLやPDF、ePubなど、構造を保ったまま様々なメディア出力ができるようにします。
過去の記事でこういうものがありました。よくまとめられたスライドです。
（必見ですよー）
ドキュメントシステムはこれを使え2015年版こちらでも述べられているように、書きやすさ、読みやすさ、管理しやすさ（プレーンテキストでバージョン管理など）、変換作業や自動化を見比べます。
結局使ってみないとわからない
ツールのWebサイトを見て回りましたが、これから作成するのでどんな問題があるのかわからないという結論です。最初はAsciiDocやAsciiDoctorを考えていました。またoreilly社のAtlasなども面白そうだなと思ったのですが、レジストレーションコードってどうするの？ってところでつまづいてしまいました。そこで、一時期使ったことのあるSphinxにすることにしました。何の不満もなかったですし、おそらくPythonコードを引用することが多いなら正しい選択でしょう。(*^ ^*)
Sphinxの拡張性
とにかくSphinxに関しては情報が多いので、困ったことがあればなんとかなるだろうという安心感はあります。また、拡張性も高いので必要に応じて機能を追加することも出来ます。テキスト作成なので（私はVimで入力します）、後から調整が効くということが重要です。
Sphinxのインストール(anaconda環境以外の場合)
日本語による検索をONにする
そのままではせっかくの検索機能が使えません。検索機能をONにするにはconf.pyに以下を追記します。html_search_language = 'ja'
