tanaka's Programming Memo

プログラミングについてのメモ。

reStructuredTextをVSCodeでプレビューする

reStructuredText Sphinx VSCode

Godotのドキュメントの翻訳に少しずつ参加しています。GodotのドキュメントはreStructuredTextというマークアップテキストが採用されています。はじめて使うので正しく動くかや空白の入れ方が結構シビアで何かと不安なので、手元の環境でプレビューできる環境を構築してみました。

目次

ブログの環境

この記事は以下の環境で確認しました。

前準備

まずはPython3.9以降とpipが動作するかを確認します。pipが動かなくなっていたことでかなり苦戦しました。事前に動作を確認して、必要に応じてインストールや修復をしてから先に進んでください。

Pythonとpipのバージョン確認

PowerShellなどのターミナルを起動して以下を実行します。

python --version
pip --version

以上でPython3.9以降とpipのバージョンが確認できれば先に進んでください。

Pythonが古かったりインストールされていない場合は、Windows版Pythonのインストール: Python環境構築ガイド - python.jpを参考にインストールしてください。インストールの際には環境変数を設定するオプションを付けましょう。

pipがエラーになる場合

Pythonをインストールすればpipも入るはずなのですが、pipがエラーで実行できないという場合は環境変数に古いものが残っている可能性があります。自分はこれでハマりました！　以下の手順で解消できるかも知れないので試してみてください。

  • システム詳細設定を開きます

システムの詳細設定を開く

自分の環境では、以上でエラーがなくなりました。

Sphinxのインストール

reStructuredTextはSphinx(スフィンクス)というツールでプロジェクトを作成したり、HTMLなどへの変換ができます。pipでインストールします。

  • PowerShellなどを起動します
  • 以下を実行します
pip install -U sphinx

-Uスイッチを付けることで、インストールされていなければインストール、インストール済みなら最新版に更新してくれます。

reStructuredTextを扱うためのプロジェクトを作成する

reStructuredTextをレンダリングするにはいくつかの設定が必要です。sphinxで簡単なプロジェクトを作って利用します。

  • PowerShellなどで、プロジェクトフォルダーを作りたい場所へcdで移動します
  • プロジェクトを作成する以下のコマンドを実行します。以下はrst-viewというプロジェクト名にする例です。プロジェクト名は任意に変更してください
sphinx-quickstart rst-view

選択肢が表示されるので次のように答えます。

  • Separate source and build directoriesは任意で。シンプルにするならそのままEnterを押します
  • Projet name:には、rst-viewなどのプロジェクト名を入力します
  • Author name:には、著作者名を入力します。公開しないなら適当でいいです
  • Project release []:は空欄のままEnter
  • Project languageは、日本語ならjaを入力してEnterします

以上で作成完了です。

VSCodeを設定する

作成したプロジェクトをVSCodeで開いて、必要なエクステンションを入れます。

  • VSCodeを起動します
  • FileメニューからOpen Folderを選択して、sphinxで作成したプロジェクトフォルダーを開きます。例でrst-viewという名前にしたフォルダーです
  • フォルダーの作成者を信頼するか表示されたら、信頼(Yes, I trust the authors)をクリックします
  • FileメニューからSave Workspace As...をクリックします
  • そのままEnterきーを押してワークスペースを保存します

保存したワークスペースに設定が書き込まれます。また、次回以降はこのワークスペースファイルをダブルクリックすればプロジェクトを開くことができます。

必要なエクステンションをインストールします。

  • 左のメニューからExtensionメニューをクリックします

エクステンションを開く

  • 検索欄にesbonioと入力して、表示されたらInstallをクリックします

Esbonioをインストール

  • Pythonもインストールします

Pythonをインストール

必要なものはこれで揃いました。reStructuredTextファイルを表示しようとするともう少し設定が必要になります。

Explorerに切り替える

  • ファイルからindex.rstをクリックして開きます

右下に「Pythonコマンドが実行できない」というようなエラーが表示されたら、Pythonの実行環境を設定する必要があります。

  • WinならF1キー、MacならShift+Command+Pキーを押して、コマンドパレットを開きます
  • Python: Selectと入力すると、Python: Select Interpreterが表示されるので選択します

Pythonのインタープリターを選択

  • Pythonの実行環境の候補が表示されるまで待ちます。候補が表示されたらPython3.9以降のものを選択します。以下はPython3.11を選択している例です

使用するPythonを選択

Pythonの実行環境をVSCodeに反映させるために一度VSCodeを閉じます。ワークスペースファイルを保存したので、プロジェクトフォルダーを開いてワークスペースをダブルクリックすればreStructuredTextのプロジェクトを開き直すことができます。

ワークスペースを開く

  • 先ほどと同じ操作でindex.rstを開きます
  • 今度はPythonが見つかるので、Language Serverをインストールするかの確認が表示されます。Yesをクリックしてインストールしてください

言語サーバーをインストールする

VSCodeのターミナルが起動してインストールがはじまるので終わるまで待ちます。インストールが終わったら「press anky key to close it.」というようなメッセージが表示されるので、何かキーを押せば完了です。

reStructuredTextをプレビューする

ここまでの設定が完了したら、あとはこのワークスペースを開いて、エディター右上のプレビューボタンを押せばreStructuredText形式のテキストファイルをプレビューすることができます。

プレビューボタン

右側にプレビューが表示されます。

プレビュー！

rstファイルを変更して保存をしたら、プレビューに反映されます！

まとめ

以上、Godotのドキュメントで使用されているreStructuredTextをVSCodeで表示する手順でした。Windowsで手順を示しましたが、MacのVSCodeでも同様の方法でプレビューできます。Pythonを仮想環境で構築したりショートカットが違うなどはありますが流れは同じです。

以前はreStructuredTextのエクステンションが使われていたのでネットではそちらの情報も見つかります。SphinxがバージョンアップしてVSCodeがEsbonioに対応したことから、2024年2月現在はこのブログで紹介した方法になりました。必要なエクステンションがEsbonioとPythonだけになり、Pythonのインタープリターの選択と言語サーバーのインストールをすれば動くので手順が簡単になりました。

Python3.9以降とpipが入っていればスムーズに設定できるのではないかと思います。

関連URL