概要

MacでSphinxを動かす．
Python3を入れてvirtualenvwrapperを使って環境を汚さないようにする．

Python3

Homebrewでインストールする

$ brew install python3
% python3 -V
Python 3.6.4

virtualenvwrapper

VIRTUALENVWRAPPER_PYTHON を設定しないと，システム標準の /usr/bin.python を見に行ってしまう．
virtualenvsにPATHを通してactivateしたコマンドを見られるようにする

$ pip3 install virtualenvwrapper
$ vim ~/.zshrc
export PATH=$HOME/.virtualenvs/:$PATH
export VIRTUALENVWRAPPER_PYTHON=/usr/local/bin/python3
if [ -f /usr/local/bin/virtualenvwrapper.sh ]; then
  export WORKON_HOME=$HOME/.virtualenvs
  source /usr/local/bin/virtualenvwrapper.sh
fi
$ source ~/.zshrc
virtualenvwrapper.user_scripts creating /Users/<user>/.virtualenvs/premkproject
virtualenvwrapper.user_scripts creating /Users/<user>/.virtualenvs/postmkproject

sphinxのプロジェクトがあるディレクトリに移動する

$ cd /your/sphinx/project
$ vim enable.sh
# !/bin/bash
# sphinxビルド用の環境に切り替える
workon <env name>

sphinxでプロジェクトを作る

Windows版の例に従ってプロジェクトを作る

ライブリロード

$ cd /your/sphinx/project
$ vim server.py
# !/usr/bin/env python

from livereload import Server, shell

server = Server()
server.watch('**/*.rst', shell('make html'))
server.serve(open_url=False)

使い方

sphinxのプロジェクトに移動してライブリロードを起動する．

$ cd /your/sphinx/project
$ sh enable.sh
(env name) $ server.py
[I 180215 15:57:01 server:283] Serving on http://127.0.0.1:5500
[I 180215 15:57:01 handlers:60] Start watching changes
[I 180215 15:57:01 handlers:62] Start detecting changes

rstファイルの更新を検知して， http://127.0.0.1:5500/build/html/index.html にビルド結果が表示される．

VS codeで.rstファイルのインデントを設定する

EditorConfig for VS Code をインストールする．
次にsphinxプロジェクトのルートディレクトリに .editorConfig ファイルを置く

root = true

[*]
charset = utf-8
end_of_line = lf
indent_size = 2
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = space

[*.rst]
indent_size = 3

.rstファイルを試しに作ってみて，インデントがスペース3つになっていることを確認する．

参考にしたドキュメント

Python Livereload を使って Sphinx でドキュメントを書く
 Windows環境でメンテしやすいドキュメントをSphinxで作る(rst形式, Markdown形式)
Sphinxを使って自分用技術メモをAtom / VSCodeで取る時にやっていることの紹介
 Visual Studio Codeを使ってみる