Sphinx(reStructuredText)のエディタ選択の話

先日Githubが落ちて午前中が仕事にならなかった皆様、いかがお過ごしですか。
技術研究所の（ほ）です。

突然ですが、仕様書などの各種ドキュメントを作る際には、みなさんは何を使っていますか。

私は、「ドキュメントを作りたくなってしまう魔法のツールSphinx」を推しているので、
今日はSphinxを使うためのエディタについて書きたいと思います。
（ベストなものは見つけられませんでしたが、お付き合いください。）

Sphinxとは、Pythonで作られたドキュメント生成ツールです。

詳しくは、上記のリンクなどや本家を見ていただければ分かると思いますが、
Markdownに似たreStructuredTextというフォーマットで記述することで、
HTML, PDF, EPUBなどで出力することが可能です。

Sphinxの良いところは、体裁と中身の記述を分離できることだと思っています。

私はドキュメントは体裁も中身も大事だとは思っているのですが、
Wordのようなツールを使った場合には
いつも両方を同時に実現しようとして下記の状況に陥ってしまい、
モチベーションが下がってしまいます。

1. いいこと考えた。
2. ドキュメント書くぜ ⤴
3. 見た目も綺麗に読みやすくしないといけないな。
4. 綺麗にならないな。ドキュメント書くの面倒 ⤵

他にもExcelを使った場合には、

• 見た目のイメージを作るのはいいけど、更新が大変。 ← 自分で仕事増やしている。
• 差分の確認が大変。 ← こっちも自分で仕事増やしている。

なので、体裁と中身の記述を分離できるSphinxはかなり(・∀・)ｲｲ!!。

弊社では、部署の垣根を超えたプレゼンを行える場があります。（リフレッシュMeetup）
他の人の感想を聞いてみたいと思い、そこで紹介してみたのですが、
下記のようのなお言葉を賜りました。

「それって、お前だから出来るんじゃね？」

• 記法が難しい。学習コストが高い。
• ビルドしないと出来上がりが分からないから使いにくい。
• 個人のPCにビルド環境を作るのが難しい。

つまり、Sphinxを他の人にも使ってもらうためには下記を満たすエディタが必要と思いました。

• 記述のサポートが必要。
• プレビューが必要。
• ビルド用のサーバが必要。

これらのすべてを満たす夢のようなツールを探したのですが、残念ながら見つけられませんでした。

ですが、記述サポートとバージョン管理、ビルドを行える Notex.sh というオンラインエディタがありました。

https://www.notex.ch/

ただし、ドキュメントを作るとパブリックな状態で保存されてしまうため、
お試しの際には記述内容に注意してください。

実際に使うとしたら、ソースがGithubで公開されているため、
プロジェクトにクローズされた環境に立てて使うことになるかもしれません。

基本的にはREADME.mdに記載のとおりで使えるようになりました。

下記のDockerfileでJDKを落としてきているのですが、恐らく作者のDropboxから落としています。

https://github.com/hsk81/notex-v2.0/blob/master/Dockerfile

正規の場所ではないところから落としたJDKを使うのことに、少し不安を感じてしまいます。

ということで、最新(Java7としては)を自前で落として、ADDするように変更しました。

あと、Proxy環境にインストールしたいという人は、かなり苦労するかもしれません。
実は、私も試したのですが、まだ成功していません。
ですので成功しましたら、またここでDockerfileを公開するかもしれません。

結局、導入障壁を下げるベストなエディタは決まりませんでした。
Sphinx普及への道は険しいですね。

私自身はビルド環境などは問題ないので、取りあえずは気軽に使うために、
Atomエディタに rst-preview-pandoc というプレビュー用のPackageをインストールして使っています。

仕方がないから、何か作るか。。。