Scoopで行うSphinx環境構築
目的
WindowsでSphinxを使ってドキュメントを作成する環境を作ります。
html と pdf で出力できるようにします。
必要モジュールのインストールを簡略化するためにパッケージ管理ツールの scoop を使います。
せっかちな人向け
せっかちな人は、以下のリポジトリをCloneして、中にあるPowerShellスクリプトを実行してください。
Scoopのインストール
まずは Scoop のインストールと、今後の操作に必要なモジュールをインストールします。
PowerShellから以下のコマンドを実行してください。
# 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のインストール
Scoopを用いてSphinxの実行に必要な Python をインストールします。
本手順では Python3.7 をインストールしています。
# install python3.7
scoop install python37
次にSphinx用に仮想環境(venv)を作成します。
本手順では仮想環境は c:\venv\sphinx に作ることを想定しているので、必要に応じて変更してください。
# create venv
python37 -m venv c:\venv\sphinx
c:\venv\sphinx\Scripts\activate.ps1
# upgrade pip
python -m pip install --upgrade pip
Sphinxのインストールとテンプレートプロジェクトの作成
環境の準備ができたのでSphixのインストールを行っていきます。
# 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 をインストールします。
# install theme `sphinx_rtd_theme`
pip install sphinx_rtd_theme
下記のように ./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 を編集します。
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に保存したものを、文書化する場合は以下のように変更します。
.. toctree::
:glob:
notebooks/*
html文書の作成
以下のコマンドを実行して、html文書を作成します。
# build html document
./make html
# 成果物の表示
./build/html/index.html
pdf出力
SphinxからPDFを出力できるようにします。
scoopで latex と perl をインストールして、 conf.py の設定を変更します。
# install latex
scoop install latex
scoop install perl
# 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文書を作成します。
# build pdf document
./make latexpdf
# 成果物の表示
./build/latex/*.pdf
初回実行時はLaTexが必要なモジュールをインストールするために、以下のダイアログが表示されます。
「Install」ボタンをして先に進みます。
このダイアログは何度も表示されるので、面倒な場合は赤線部分の「Always show this daialog ～」のチェックを外すと、以降はこのダイアログは表示されなくなります。
Enjoy Sphinx!!
以上で完了です。
上記の手順は ここ にスクリプトとして置いてありますので、ご活用ください。
Sphinxを使ってどんどんドキュメントを作っていきましょう!!
Discussion