Prerequisites

This article shows what dependencies are required by different features.

Install Python for Most Features

reStructuredText is a technology created by Python community, so most of the toolchain is built upon Python. It is very important to install Python in advance.

  1. Download Python version 3.8 or above (old versions might work, but no guarantee).

    Note

    pyenv and pyenv-win are recommended to manage multiple Python versions on the same machine.

    Note

    You can refer to Python official page to learn which versions should not be used.

    Note

    Latest steps on how to install Python and Sphinx, please refer to this article.

  2. Once Python is installed, make it available to this extension via either option,

    • Option 1: Use the Python extension by Microsoft.

      Note

      It really makes configuring Python environment easier for users in this approach.

      Once you have that Python extension installed, open conf.py in VSCode. The Python extension shows an extra button in the status bar from where you can select which Python installation to use.

    • Option 2: Add Python to system path (especially on Windows).

      Note

      If you are installing on Windows, ensure both the Python install directory and the Python scripts directory have been added to your PATH environment variable.

      For example, if you install Python into the c:\python38 directory, you can add c:\python38;c:\python38\scripts to your PATH environment variable.

      However, do consider a solution like pyenv to manage multiple Python versions on the same machine so that you can switch easily among them.

    • Option 3: Use VSCode setting python.pythonPath to tell this extension where to locate Python.

      Note

      This setting is not recommended because Microsoft Python extension is moving away from this setting.

Virtual Environments

Python virtual environment is partially supported,

  • pipenv users should refer to #407

  • venv users should refer to #409

  • conda users should refer to #410

Important

Other sections of this documentation site might use commands such as pip install which are not virtual environment friendly.

It is your own responsibility to replace them with virtual environment specific commands such as pipenv install or conda install.

You should use a solution like pyenv to manage multiple Python versions on the same machine so that you can switch easily among them.

Install Esbonio Language Server for Live Preview and IntelliSense

Danger

Starting from version 190.1.17, this requirement is removed. You will be recommended to install Esbonio extension instead. To learn more about how to configure Esbonio, you must visit this site.

Install Doc8 or RstCheck as Linter

Linting support can use the doc8 or rstcheck engine.

  1. Install doc8 to enable linter support.

    pip install doc8

    Note

    If you prefer not to use doc8, then this step is optional.

  2. Install rstcheck to enable linter support.

    pip install rstcheck

    Note

    If you prefer not to use rstcheck, then this step is optional.