📑

Scoopで行うSphinx環境構築

5 min read

目的

WindowsでSphinxを使ってドキュメントを作成する環境を作ります。
htmlpdf で出力できるようにします。
必要モジュールのインストールを簡略化するためにパッケージ管理ツールの scoop を使います。

せっかちな人向け

せっかちな人は、以下のリポジトリをCloneして、中にあるPowerShellスクリプトを実行してください。

https://github.com/rhenerose/build_sphinx_environment_using_scoop

Scoopのインストール

まずは Scoop のインストールと、今後の操作に必要なモジュールをインストールします。

PowerShellから以下のコマンドを実行してください。

Scoop がインストール済みの方は本手順は不要です。

Scoopのインストール
# install scoop
Set-ExecutionPolicy RemoteSigned -scope CurrentUser
Invoke-Expression (New-Object System.Net.WebClient).DownloadString('https://get.scoop.sh')

# install basic module
scoop install aria2
scoop install git

# add bucket
scoop bucket add extras
scoop bucket add versions

ポリシー変更に関するメッセージが表示された場合は y を入力して先に進んでください。

Pythonのインストール

Python がインストール済みの方は本手順は不要です。

Scoopを用いてSphinxの実行に必要な Python をインストールします。
本手順では Python3.7 をインストールしています。

Pythonのインストール
# install python3.7
scoop install python37

次にSphinx用に仮想環境(venv)を作成します。
本手順では仮想環境は c:\venv\sphinx に作ることを想定しているので、必要に応じて変更してください。

仮想環境(venv)の作成
# create venv
python37 -m venv c:\venv\sphinx
c:\venv\sphinx\Scripts\activate.ps1

# upgrade pip
python -m pip install --upgrade pip

Sphinxのインストールとテンプレートプロジェクトの作成

以降の作業は上記で作った仮想環境で実行することを想定しています。

環境の準備ができたのでSphixのインストールを行っていきます。

Sphinxのインストール
# install sphinx
pip install sphinx

Sphixがインストールできたらテンプレートプロジェクトを作成します。
本手順では c:\sphinx_doc に作成することを想定しているので、必要に応じて変更してください。

テンプレートプロジェクトの作成
# create project directory
mkdir c:\sphinx_doc
cd c:\sphinx_doc

# create template project
# 必要に応じてオプションの project, author, release を変更してください
sphinx-quickstart --sep --project='your_project' --author='your_name' --release='1.0.0' --language='ja'

ここで指定したオプションは ./source/conf.py に記載されるため、後からでも変更可能です。

テーマの変更

Sphinxのテーマを変更します。
テーマに関してはここ(https://sphinx-themes.org/)で好みのものを探してください。
本手順では sphinx_rtd_theme をインストールします。

テーマ(sphinx_rtd_theme)のインストール
# install theme `sphinx_rtd_theme`
pip install sphinx_rtd_theme

下記のように ./source/conf.py を編集して、テーマを変更します。

./source/conf.py
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

SphinxでMarkdownおよびNoteBookを使えるようにする

SphinxでMarkdownとNoteBookを使えるようにします。

各種モジュールのインストール
# install other extention
# for `.md`
pip install recommonmark
pip install sphinx-markdown-tables

# for `.ipynb`
pip install ipython
pip install nbsphinx
scoop install pandoc

下記のように ./source/conf.py を編集します。

conf.py
extensions = [
    'recommonmark',
    'nbsphinx',
    'sphinx.ext.mathjax',
    ]

source_suffix = ['.rst', '.md']
source_parsers = {
    '.md': 'recommonmark.parser.CommonMarkParser',
}

exclude_patterns = ['**.ipynb_checkpoints']

index.rst の更新

必要に応じて、index.rstを更新してください。
例えば、Notebook形式のファイルを./notebooksに保存したものを、文書化する場合は以下のように変更します。

index.rst
.. toctree::
   :glob:

   notebooks/*

html文書の作成

以下のコマンドを実行して、html文書を作成します。

html文書の作成
# build html document
./make html

# 成果物の表示
./build/html/index.html

pdf出力

SphinxからPDFを出力できるようにします。
scoopで latexperl をインストールして、 conf.py の設定を変更します。

LaTeXのインストール
# install latex
scoop install latex
scoop install perl
./source/conf.py
# LaTeX設定
latex_engine = 'lualatex'

# LaTeXドキュメントクラスとしてltjsbookを使用する
latex_docclass = {'manual': 'ltjsbook'}

latex_elements = {
    'polyglossia': '',  #polyglossiaを読み込まない (大量エラー対策)
    'fontpkg': r'''
\setmainfont{DejaVu Serif}
\setsansfont{DejaVu Sans}
\setmonofont{DejaVu Sans Mono}
''',
    'preamble': r'''
\usepackage[titles]{tocloft}
\cftsetpnumwidth {1.25cm}\cftsetrmarg{1.5cm}
\setlength{\cftchapnumwidth}{0.75cm}
\setlength{\cftsecindent}{\cftchapnumwidth}
\setlength{\cftsecnumwidth}{1.25cm}
''',
    'fncychap': r'\usepackage[Bjornstrup]{fncychap}',
    'printindex': r'\footnotesize\raggedright\printindex',
}
latex_show_urls = 'footnote'
'''

pdf文書の作成

以下のコマンドを実行して、pdf文書を作成します。

pdf文書の作成
# build pdf document
./make latexpdf

# 成果物の表示
./build/latex/*.pdf

初回実行時はLaTexが必要なモジュールをインストールするために、以下のダイアログが表示されます。
「Install」ボタンをして先に進みます。

このダイアログは何度も表示されるので、面倒な場合は赤線部分の「Always show this daialog ~」のチェックを外すと、以降はこのダイアログは表示されなくなります。

Enjoy Sphinx!!

以上で完了です。
上記の手順は ここ にスクリプトとして置いてありますので、ご活用ください。

Sphinxを使ってどんどんドキュメントを作っていきましょう!!

Discussion

ログインするとコメントできます