Environment Setup

Environment Setup#

We use Sphinx for building and formatting the html files. To add to the documentation, we use a combination of VSCode extensions and terminal commands which allow a quick and simple way of writing documentation and viewing it live.

Prerequisites#

Before starting this setup guide, ensure that the following programs and extensions are installed. For the VSCode extensions, install them in the same instance as where the rest of the control code is edited.

Note

Don’t forget to add the make binary to path, it is called during building.

Python#

Since Sphinx is based on python, it is required to have the correct packages installed. First, restart VSCode to restart all of the extensions. Then, open the Command Palette and run Python: Select Interpreter. Choose the python version you installed as the prerequisite and hit enter.

Important

There is a known bug with the Esbonio extension where it does not support spaces in the python binary path. Make sure to select an installation in Program Files on any other directory without a space

After selecting the python installation, open terminal by pressing Ctrl+Shift+` and run the following commands.

cd docs
pip install -r requirements_dev.txt

Finally, restart VSCode to re-run the python extensions.

Configuration#

Note

This step is optional since there is already a settings.json in the project, however if something does not work, make sure to check that all of these settings are correct.

Once all of the extensions are installed, open the user settings.json from the Command Palette Ctrl+Shift+P and make sure to set the esbonio and lint paths.

"restructuredtext.linter.doc8.extraArgs": [
  "--config",
  "${workspaceFolder}/docs/doc8.ini"
],
"esbonio.sphinx.numJobs": 0,
"esbonio.sphinx.buildDir": "${workspaceFolder}\\docs\\build",
"esbonio.sphinx.confDir": "${workspaceFolder}\\docs\\source"

To view the rst file updates live, we use the filewatcher and livePreview extensions together.

"filewatcher.commands": [
  {
    "event": "onFileChange",
    "match": "\\.rst*",
    "cmd":"\"${workspaceRoot}\\docs\\make.bat\" html"
  }
],
"livePreview.defaultPreviewPath": "docs/build/html/index.html",
"livePreview.previewDebounceDelay": 3000

Additionally, to have the preview automatically change as you type, set the autosave delay around 1000

"files.autoSave": "afterDelay",
"files.autoSaveDelay": 1000

Editing#

When editing the documentation, open the Command Palette by pressing Ctrl+Shift+P and run Live Preview: Start Server while an rst file is open.

Note

If the live preview window can’t find the html file, try to cause a rebuild by editing a rst file. Make sure that the docs/build directory is being created since that is where the live preview points to. Finally, if it still doesn’t work, open the output panel by pressing Ctrl+Shift+U and select Esbonio from the dropdown in the top right. If everything is working, the output should show something about build succeeded..

Manual Building#

If you just pulled new changes or want to preview the documentation without live editing the files, it is possible to build it through the terminal.

cd docs
./make html # run make.bat, if using command prompt ./ is not needed

The output html files should be put in the same docs/build directory that the live preview builds in. Now you can open them in a browser or start the Live Preview server to view them inside VSCode.