VSCODEでsphinxの自動ビルド環境を構築する

やらなければいけないこと

・モジュールの２つのインストール
・batファイルの編集
・batファイルをターミナルで常駐させる

発端

本来であればRSTViewerを使うのが鉄板なのですが、言語サーバーとパフォーマンスに問題があるらしく、結局地味にビルドした方がいいらしい。

で、オートビルド機能があるので、いくつかありますが、make.batをいじる形を試してみる。

参考

WindowsのVSCodeでsphinxドキュメントを作るために必要な最低限の設定3選 | はますけブログ

まず、オートビルドのモジュールを追加。
私の環境ではコアの監視モジュールのwatchfilesもインストールしないと駄目でした。

pip install sphinx-autobuild

pip install watchfiles    

次にmake.batを編集。
４行の追加分を追加（コメントは省いて）

@ECHO OFF

pushd %~dp0

REM Command file for Sphinx documentation

if "%SPHINXBUILD%" == "" (
	set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
set BUILDDIR=build

%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
	echo.
	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
	echo.installed, then set the SPHINXBUILD environment variable to point
	echo.to the full path of the 'sphinx-build' executable. Alternatively you
	echo.may add the Sphinx directory to PATH.
	echo.
	echo.If you don't have Sphinx installed, grab it from
	echo.https://www.sphinx-doc.org/
	exit /b 1
)

@REM ライブファイルの追加文
if "%1" == "livehtml" goto livehtml
@REM ライブファイルの追加文終了

if "%1" == "" goto help

%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end

@REM ライブファイルの追加文
:livehtml:
sphinx-autobuild %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end
@REM ライブファイルの追加文終了


:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

:end
popd

引数でlivehtmlが入力されたら、オートビルドを実行するというbatファイルです。
実行は

make.bat livehtml

を実行

成功するとbatファイルが動き続けてファイルが保存されると勝手にビルドします。
下記のサーバーのアドレスをクリックすると自動でHTMLが更新されてリアルタイム（ビルド）でHTMLを確認できます。

なお、本当にINDEX.htmlファイルがビルドされてるわけではなく、
監視用のジェネレートファイルが別途作られてビルドされてます。
ですので、コードが完成したらmake.bat htmlで正式にビルドする必要があります。

常に実行中ですので、batファイルを終了したい場合は、ctrl+cでターミナルで終了させてください。