概要
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を使ってみる