VSCodeとDockerで快適なSphinx(reStructuredText, rst)編集環境を作る

弊社のプロジェクトではドキュメントをSphinx(rst)で書くことになっているのですがあまり普段rstを書くことがないので、なにかの手助けがないとスラスラドキュメントが書けません。
今回はVSCodeとDockerを使っていい感じに補完、lint, previewができる環境を構築します。
rst用のVSCodeプラグインとしてreStructuredText - Visual Studio Marketplaceがあるので、それをインストールすれば出来上がりかと思ったのですが、ちょっと面倒な設定が必要だったのでまとめた次第です。

Dockerなしで使う

ドキュメントはreStructuredText Extension for Visual Studio Code — restructuredtext 1.0 documentationにあり、書かれているとおりに環境を作ってあげれば動くようになります。ただ、pip moduleをglobalにインストールさせようとしているあたりが自分のPythonプロジェクトの開発手法と相容れないところがあり、この方法は取りませんでした。

普段自分はpyenv + pipenvでproject毎にPython環境を切り替えています。上記のマニュアルによるとvirtualenvも対応しているようなので、正しく設定すれば僕の普段の環境でも使えるようになるはずですが、困ったことに設定が複雑になるとの理由でドキュメントから説明が省かれてしまっています。

Dockerを使う

Dockerで環境を固めて、コンテナにVSCodeでアタッチする形で使えば環境がポータブルにできるので、今回はそちらの方法で環境構築します。
Sphinxの公式Docker imageはSphinxdoc/sphinxにあるので、このimageをベースにします。

このimageにPrerequisites — restructuredtext 1.0 documentationで定義されている依存モジュールを入れてあげればよいことになるので、下記のように定義しました。

Dockerfile

FROM sphinxdoc/sphinx:3.2.0

RUN mkdir /workspace
WORKDIR /workspace

RUN python3 -m pip install --no-cache-dir \
    docutils sphinx-autobuild doc8 rstcheck \
    sphinx_rtd_theme sphinxcontrib-httpdomain

docutilsはsphinxを使うのであれば必要なく、doc8とrstcheckはどちらか好きな方で良いですが面倒なので全部入れています。sphinx_rtd_themeとsphinxcontrib-httpdomainはプロジェクトで必要だったので入れています。

あとは、imageをbuildしてコンテナを作って、VSCodeからコンテナ起動、中に入ってドキュメントを編集します。
reStructuredText - Visual Studio Marketplaceはremote containerにもインストールする必要があるので注意が必要です。