📘

VSCodeでSphinxドキュメント作成環境を整える

2023/05/01に公開

Python

はじめに

SphinxというPython製のドキュメント作成ツールがあります。テキストベースで記述したファイルをHTMLやPDFに変換することができて便利なのですが、変換にはビルドを伴うので、少し面倒です。
そこで、VSCodeに拡張機能を入れてライブプレビューをしながら記述できる環境を整えたので、その方法をメモしておこうと思います。

ちなみに、Pythonの公式ドキュメントや、Linux KernelのドキュメントなどがSphinxで作成されています。その外にもOSS（特にPython関連）のドキュメントはSphinxで作成されているものが多いです。こちらに採用例が載っていました。

では、以下の流れでメモしていきます。

Sphinxインストール
Sphinxプロジェクトの作成
VSCodeの拡張機能追加と設定
プレビュー表示

1. Sphinxインストール

Pythonのインストール

SphinxはPythonで書かれていて、実行にはPythonが必要ですので、まずはPythonをインストールします。
https://www.python.org/ からインストーラーをダウンロードしてインストールします。

仮想環境の作成

Sphinxドキュメントを作成するワークスペース（フォルダ）を作成して、そこにPythonの仮想環境（VENV）を作ります。
今回の手順ではSphinxをPIP経由でインストールします。
グローバル環境にインストールしても良いのですが、個人的にはプロジェクト毎に専用の環境を作って、ローカルインストールしておいた方がプロジェクト毎に必要なライブラリ、バージョンが整理されるので良いと思っています。

本記事では、「C:\local\dev\sphinx_prj」にSphinxドキュメントを執筆するワークスペース（フォルダ）を作成して仮想環境を（VENV）を作成しています。

PS C:\local\dev\sphinx_prj> python -V
Python 3.10.11
PS C:\local\dev\sphinx_prj> python -m venv .venv
PS C:\local\dev\sphinx_prj>

なお、この後の手順でインストールする拡張機能の Python がデフォルトでワークスペースの直下にある .venv フォルダを仮想環境へのパスとして読み取ってくれるため、 .venv という名前で作成しています。
VSCode上でのPython環境の詳細についてはこちらに解説がありました。

Sphinxのインストール

Sphinxをインストールします。本記事では、PIPコマンドでPyPIからインストールします。
他の方法については Sphinxのドキュメントを参照してください。
仮想環境（VENV）をActivateしてからインストールします。

PS C:\local\dev\sphinx_prj> .\venv\Scripts\activate
(.venv) PS C:\local\dev\sphinx_prj> pip install -U sphinx
Collecting sphinx

--- SNIP ---

Installing collected packages: snowballstemmer, urllib3, sphinxcontrib-serializinghtml, sphinxcontrib-qthelp, sphinxcontrib-jsmath, sphinxcontrib-htmlhelp, sphinxcontrib-devhelp, sphinxcontrib-applehelp, Pygments, packaging, MarkupSafe, imagesize, idna, docutils, colorama, charset-normalizer, certifi, babel, alabaster, requests, Jinja2, sphinx
Successfully installed Jinja2-3.1.2 MarkupSafe-2.1.2 Pygments-2.15.0 alabaster-0.7.13 babel-2.12.1 certifi-2022.12.7 charset-normalizer-3.1.0 colorama-0.4.6 docutils-0.19 idna-3.4 imagesize-1.4.1 packaging-23.1 requests-2.28.2 snowballstemmer-2.2.0 sphinx-6.1.3 sphinxcontrib-applehelp-1.0.4 sphinxcontrib-devhelp-1.0.2 sphinxcontrib-htmlhelp-2.0.1 sphinxcontrib-jsmath-1.0.1 sphinxcontrib-qthelp-1.0.3 sphinxcontrib-serializinghtml-1.1.5 urllib3-1.26.15

2. Sphinxプロジェクトの作成

続いて、sphinx-quickstartコマンドを実行してSphinxプロジェクトを作成します。

(.venv) PS C:\local\dev\sphinx_prj> 
(.venv) PS C:\local\dev\sphinx_prj> sphinx-quickstart
Sphinx 6.1.3 クイックスタートユーティリティへようこそ。

以下の設定値を入力してください（Enter キーのみ押した場合、
かっこで囲まれた値をデフォルト値として受け入れます）。

選択されたルートパス: .

Sphinx 出力用のビルドディレクトリを配置する方法は2つあります。
ルートパス内にある "_build" ディレクトリを使うか、
ルートパス内に "source" と "build" ディレクトリを分ける方法です。
> ソースディレクトリとビルドディレクトリを分ける（y / n） [n]: n

プロジェクト名は、ビルドされたドキュメントのいくつかの場所にあります。
> プロジェクト名: example
> 著者名（複数可）: xxx author     
> プロジェクトのリリース []: 2023.4.15

ドキュメントを英語以外の言語で書く場合は、
 言語コードで言語を選択できます。Sphinx は生成したテキストをその言語に翻訳します。

サポートされているコードのリストについては、
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language を参照してください。
> プロジェクトの言語 [en]: jp

ファイル C:\local\dev\sphinx_prj\conf.py を作成しています。
ファイル C:\local\dev\sphinx_prj\index.rst を作成しています。
ファイル C:\local\dev\sphinx_prj\Makefile を作成しています。
ファイル C:\local\dev\sphinx_prj\make.bat を作成しています。

終了：初期ディレクトリ構造が作成されました。

マスターファイル C:\local\dev\sphinx_prj\index.rst を作成して
他のドキュメントソースファイルを作成します。次のように Makefile を使ってドキュメントを作成します。
 make builder
"builder" はサポートされているビルダーの 1 つです。 例: html, latex, または linkcheck。

(.venv) PS C:\local\dev\sphinx_prj> 
(.venv) PS C:\local\dev\sphinx_prj> ls


    ディレクトリ: C:\local\dev\sphinx_prj


Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d-----        2023/04/14      0:30                .venv
d-----        2023/04/14      0:54                _build
d-----        2023/04/14      0:54                _static
d-----        2023/04/14      0:54                _templates
-a----        2023/04/14      0:54           1004 conf.py
-a----        2023/04/14      0:54            457 index.rst
-a----        2023/04/14      0:54            800 make.bat
-a----        2023/04/14      0:54            634 Makefile


(venv) PS C:\local\dev\sphinx_prj>

3. VSCodeの拡張機能追加と設定

拡張機能

プレビュー機能を含む reStructuredText の拡張パック Extension Pack for reStructuredText をインストールします。
これには、 Pythonの拡張機能も含まれています。

reStructuredTextの設定

reStructuredTextによってライブプレビューができるようになります。
VSCodeの拡張機能の設定で、以下の設定を行います。パスは環境に合わせて適宜修正します。

{
  "esbonio.sphinx.confDir": "{workspaceFolder}", // conf.pyが置かれているディレクトリを指定
  "esbonio.server.enabled": true, // デフォルト true になっているはず
  "esbonio.sphinx.buildDir": "{workspaceFolder}/_build", // ビルドで生成されるHTMLファイルなどの出力先
  "restructuredtext.linter.doc8.extraArgs": ["--max-line-length", 200] // linterの設定（任意）
}

Pythonの設定

Pythonのインタプリターを前の手順で作成した仮想環境のものに設定します。
VSCodeを開いている状態で、 Ctrl + Shift + P でコマンドパレットを開き、Python と入力し、 Python: Select Interpreter を選択します。

続いて、前の手順で作成した仮想環境を選択します。

このように設定しておくと、Terminalを起動した際、自動で指定した仮想環境をActivateしてくれます。

esbonio(Language Server)のインストール

esbonioはreStructuredText用の言語サーバーです。これがないと「Esbonio language server is not installed」というエラーのトーストがでてプレビュー表示ができませんので仮想環境にインストールします。
PIP経由でインストールします。

(.venv) PS C:\local\dev\sphinx_prj> pip install esbonio
Collecting esbonio
--- SNIP ---
Installing collected packages: appdirs, typeguard, pyspellchecker, exceptiongroup, attrs, cattrs, lsprotocol, pygls, esbonio
Successfully installed appdirs-1.4.4 attrs-23.1.0 cattrs-22.2.0 esbonio-0.16.1 exceptiongroup-1.1.1 lsprotocol-2023.0.0a1 pygls-1.0.1 pyspellchecker-0.7.1 typeguard-2.13.3
(.venv) PS C:\local\dev\sphinx_prj>

4. プレビュー表示

ここまでの手順に問題がなければプレビュー表示できるようになっているはずです。
index.rst を開いて、右上のプレビュー用のアイコンをクリックしてプレビューを表示します。

VSCodeのカラーテーマを変更する

デフォルトだとVSCodeのカラーテーマは Dark+ (default dark) になっていると思います。
これでも良いのですが、実際のSphinxドキュメントの出力イメージと異なりますので、最終的なイメージを確認する際は Light+ (default light) 等に変更して確認した方が良いと思います。
左下の歯車アイコンからメニューを辿って設定を変更します。

プレビュー表示のスクロールと連動しないようにする

デフォルトだとプレビュー表示のスクロールと連動して編集中のファイルもスクロールされます。便利そうなのですが、編集箇所が移動するのは結構煩わしいので、無効にしても良いと思います。（ここは好みで）
Settings画面を開いて、 restructure preview scroll と入力します。

まとめ

以上で、VSCodeでSphinxドキュメントを作成する環境の準備が整ったと思います。
ライブプレビューができると、ビルドしなくて済むので効率よくドキュメント作成ができますね。