Sphinxを使って自分用技術メモをAtom / VSCodeで取る時にやっていることの紹介

発表資料

これは#ssmjp 2016/07の発表資料用の記事です

---

何故この話をするか？

A. この組み合わせの情報をあまり見かけないから

• Sphinx
• Atom
• VSCode

---

伝えたいこと

「実際にこうやっている」という例の提示

---

深い話はしない

SphinxとAtom / VSCodeを組み合わせて使う時のちょっとしたコツについて話す。

個別の技術の深い話は各種書籍や公式ドキュメントに委譲。

• 『Sphinxをはじめよう』
• 『Atom実践入門』

---

注意事項

• 過剰なエディタ宗教戦争論議はする予定なし
• 個人的な見解多め
• 2016年7月現在の情報
  • 陳腐化する箇所もある
  • 特にエディタとそのプラグイン関連

---

自己紹介

• 清水 琢(@takuan_osho)
• Sphinxとの関わりは2011年2月のSphinx翻訳ハッカソンから
• 今までで一番大きなSphinxへの貢献はepub3ビルダーのプルリクエスト
  • 1.4からExperimentalとして使用可能になった (それについて書いたブログ記事)
• 現在のメインエディタはAtom、サブエディタはVSCode
  • エディタ変遷はVim -> Emacs(Evil mode) -> Sublime Text -> Atom or VSCode
  • 今でもVimやEmacsは使う

---

結論

• Sphinxはメモをまとめるのに適している
• Sphinx形式のドキュメントの場合、Atomの方が柔軟に対応出来る
• Atom / VSCodeの場合、Sphinx(reST)に関するプラグインの成熟度には期待しすぎない方がいい

---

「(技術)メモ」のここでの定義

ここでは「プログラミングのコードも含めて、後で楽に復習、参照できるようにした軽めの技術文章」くらいの軽い意味として使う。

---

Sphinxはまとめる場

言い換えると、「Sphinxは最初のメモ書きに適さない」ということ。

---

なぜ最初のメモ書きに適さないのか

• Sphinxの特徴である「内容と構造の分離」
  • 内容と構造がどちらも決まってないとキツい
• まずメモで内容を固定。次に構造化をした方が上手くいく。
  • 内容を書きたいだけの時にはSphinxの構造化に関わる構成、機能は却って邪魔になりがち

---

メモの受け皿となる場所を用意する

すぐに書き留められる場(書くハードルがなるべく低いもの)を1つ別に用意しておく。

GTDのInboxのような、メモの受け皿となる仕組みが別途あった方がよい。

• ノート
  • 手書き
• Slack
  • 分報チャンネル
  • 自身のプライベートチャンネル
  • 自分用アカウント

---

メモの受け皿を使う時のコツ

• 後でたどれるように、仕組みに応じた印をつけておく
  • Slackならスターをつける
• なるべく間を置かずに、時間を見つけて or 作ってSphinxにまとめる。
  • 間を置くと辿りづらくなるため
  • GTDにおける週次レビュー的な感じ

---

小さく始める

メモなので最初は小さく、でも大きくなっても耐えられるようにする

• 自動ビルド
• プロジェクトをまたいだファイル操作
• バージョン管理

---

Atom / VSCodeでそれらの仕組みを実現するやり方

だいたいプラグインかデフォルトの機能で実現できる。

自動ビルド

sphinx-autobuild + terminal-plus (Atom) or integrated terminal (VSCode)

ファイル操作

ファイル操作系のショートカット (AtomならTreeView、VSCodeにもショートカットあり)

バージョン管理

Atom, VSCodeともにGitのサポートが手厚い

git-plus (Atom)
デフォルトのGit機能(VSCode)

---

デモ

実際にどうファイルを操作するか提示

おそらくここが一番価値があるコンテンツ(になる予定)

---

どちらがより適しているか？

技術関連のドキュメント(リファレンス的なもの)に限るなら、Atomの方が圧倒的に使いやすい。

∵ ドキュメントはファイルの行き来が多いから

---

AtomとVSCodeの使い勝手の違い

Atom

Pros

• 柔軟性が高い
  • 特にファイル操作関連 (TreeViewパッケージ)
  • 画面分割
  • どちらもショートカットでほぼできる

Cons

• 全体的に重い
• 起動が(VSCodeに比べると)遅い

VSCode

Pros

• (Atomに比べると)圧倒的な速さのコード補完
• (Atomに比べると)起動が早い

Cons

• 柔軟性が低い
  • 特にファイル操作と画面分割関連
    • ショートカットが痒いところに手が届かない

---

役立つパッケージ・Extensionの紹介

これが一番陳腐化が早いと思われる部分。

インデント

Sphinxの場合、ディレクティブを含む文章を考えると3インデントにするのがいいが、editorconfigプラグインを使うとAtom / VSCode両対応できる
- Atomのeditorconfigパッケージ
- VSCodeのeditorconfigエクステンション

root = true

[*]
indent_style = space

[*.rst]
indent_size = 3

Atomだけでいい場合、 language-restructuredtextパッケージの設定内にあるTab Lengthの値を3にすればいい。

reSTサポート

• Atom
  • language-restructuredtext
• VSCode
  • lextudio.restructuredtextエクステンション
  • snippetの種類は多いが、
  • 他にもあるが確かめきれてない

自動ビルド

sphinx-autobuildというライブラリを使って手軽に自動ビルド環境を作れる。

この時、ターミナル操作系のプラグインや機能を使うとより楽。

• Atom
  • terminal-plus
  • ショートカットを活用できる柔軟なパッケージ
  • 個人的には、これがないと仕事にならない
• VSCode
  • v1.2.0からデフォルトで追加された Integrated Terminal
  • 日本語が表示できない時期があったり、キーボードで複数開くのが面倒だったり、あまり小回りは効かない印象

バージョン管理

ターミナル操作系のプラグインや機能があればだいたい用が足りるけど、これも補助的に使える

• Atom
  • git-plus
  • 単純なコミットを一括でやってすぐにpushしたい時などに使用している
• VSCode
  • デフォルトのgit機能 (それほど使いやすくはない)
  • 単純なコミットや単純なdiffを見る場合に活用

設定同期

Sphinxとは関係が薄くなるが、これがあると自宅用と業務用で環境が統一できて楽。

• Atom
  • sync-settings
• VSCode
  • Visual Studio Code Settings Sync

その他

よく使うフォルダを登録しておくととても楽になるもの。

• Atom
  • project-manager

---

期待しない方がいいこと

プラグインの成熟度

特にreSTサポートには過剰な期待はしない方がいい

---

実際に書く時

個人的には最初は以下の書き方を押さえておけばいいと思っている

• セクション
• リスト
• code-blockディレクティブ

---

更に学びたい人のための参考資料

• Sphinxをはじめよう
• Sphinx-users.jp
• Atom実践入門