インストール方法

前提としてPython3がインストールされていること

インストール先を確認しましょう。Windowsキー押下 ‣ cmd と入力し Enter キー押下でコマンドプロンプトを起動して次のコマンドを打ち結果例のように表示される事を確認して下さい。

コマンド

cd %USERPROFILE%\AppData\Local\Programs\Python\Python36-32

dir /w

# Windows10 の場合は標準のインストールパスは `%USERPROFILE%\AppData\Local\Programs\Python\Python36-32` となります。

結果例

[.] [..] [DLLs]

[Doc] [include] [Lib]

[libs] LICENSE.txt NEWS.txt

python.exe python3.dll python36.dll

pythonw.exe [Scripts] [tcl]

[Tools] vcruntime140.dll

続いてインストールされた Python のバージョンを確認します。引き続きコマンドプロンプトに次のコマンドを打ちましょう

コマンド

python -V

※Vは大文字

表示例

Python 3.6.3

Sphinxのインストール

venv という Python3.3 以降に追加された仮想環境機能を利用して Sphinx 用の環境を作成し、Sphinx をインストールする手順を紹介します。

コマンドプロンプトを起動して Python のインストール時にメモをしたインストール先をカレントディレクトリにします

cd %USERPROFILE%\AppData\Local\Programs\Python\Python36-32

dir /w

# 既に Python インストール終了時の確認で実施している方は飛ばしてください

venv 環境をユーザディレクトリ配下にmysphinxという名前で作成します

python -m venv %USERPROFILE%\mysphinx

仮想環境に入ります

%USERPROFILE%\mysphinx\Scripts\activate

(※acticateを実行)

pipコマンドでインストールします。コマンドプロンプトに以下のようにタイプしエンターキーを押して下さい。

pip install sphinx Pillow

# 正常にインストールが完了した場合の表示例

Successfully installed Jinja2-2.10 MarkupSafe-1.0 Pillow-4.3.0 Pygments-2.2.0 alabaster-0.7.10 babel-2.5.1 certifi-2017.11.5 chardet-3.0.4 colorama-0.3.9 docutils-0.14 idna-2.6 imagesize-0.7.1 olefile-0.44 pytz-2017.3 requests-2.18.4 six-1.11.0 snowballstemmer-1.2.1 sphinx-1.6.5 sphinxcontrib-websupport-1.0.1 urllib3-1.22

Sphinx がインストールされた事を確認しましょう。

sphinx-quickstart –version

# 正常にインストールが完了した場合の表示例

Sphinx v1.6.5

※ここで 

ModuleNotFoundError: No module named ‘markupsafe._compat’

が出る場合、 markupsafeをコンパイル済みの別のものに差し替えます。

pip uninstall markupsafe

を 実行してmarkupsafeをいったんアンインストールして、 リンク先からPythonのバージョンに合わせたwhlファイルをダウンロードします。

そのwhlファイルを指定して、markupsafeをインストールし直します。

pip install ダウンロードしたwhlファイル

これで無事にsphinx-quickstartが起動できます。

プロジェクトを作る

http://sphinx-users.jp/gettingstarted/make_project.html

参照

基本使用方法

(1) まずはディレクトリを作って、その中でsphinx-quickstart。

(2) できたindex.rstを編集。

(3) index.rstに本文を全て書くんじゃなくて、階層化した方が当然楽ちん。

    ・その場合、index.rstには”.. toctree::”、次の行にスペース3個に続いて.rstを除いたファイル名を書く。

    ・index.rstと同じディレクトリに上記の名称+拡張子rstのファイルを置く。本文はこのファイルに書く。

(4) -必ずutf8で保存すること！（makeでwarninが大量に出て、ブラウザで表示すると文字化けする。）

(5) 文書が書けたら”make html”とすると、_build/htmlの下にhtmlファイルができてる。

今後の課題

• Markdownでの記述
• Gitとの連携(hookで自動ビルド)
• ドキュメントの置き場所