VS Code

For VS Code any preexisting configuration is provided via the workspace configuration in the directory <workspace_root/.vscode>. It includes

• some formatting rules

• configuration for recommended plugins

Starlark

For Starlark currently no solution is integrated in VScode.

C++

Python

For Python to work inside VS code the virtual environment needs to be selected. If not suggested automatically it can be performed manually:

Click on the Python Version which is displayed in the lower right corner of the screen and select the .venv_docs.

After selecting the virtual environment the full feature set of the official Python Extension (MIT License) is provided included features e.g. autocomplete, syntax checking, …

Also the configuration for displaying and executing pytest in the IDE is provided.

As a linter the ruff extension (MIT License) is set up.

Debugging

For usual debugging the Python Debugger (MIT License) can be used.

Debugging the docs build

For debugging the docs environment all necessary configuration is already provided. It can be activated for the incremental build via the following command:

bazel run //docs:incremental -- --debug

Debugging python code started via bazel

In rare cases where this does not fit, mostly because you want to start the tool via bazel, you can reuse the debugpy approach from //docs:incremental and use remote debugging:

1. Add following code to the project (e.g. the __init__.py)

   debugpy.listen(('0.0.0.0', <<port>>))
   print('Waiting for client to connect')
   debugpy.wait_for_client()
   

2. Create a launch configuration (can also be done automatically in VScode) similar to this

   {
   "version": "0.2.0",
   "configurations": [
      {
            "name": "Python Debugger: Remote Attach Bazel",
            "type": "debugpy",
            "request": "attach",
            "connect": {
               "host": "<<localhost or name of remote workstation>>",
               "port": "<<port number>>",
            },
      }
      ]
   }
   

3. Execute the bazel command to run the target

4. Wait till “Waiting for client to connect” appears in the output

5. Execute launch configuration

6. Enjoy debugging

Sphinx

For Sphinx development currently following features are supported:

• Syntax checking

• live-preview within IDE

• autocompletion

Therefore when you open the project you get some recommendations for extensions (open directory) or preinstalled extensions (open devcontainer). A configuration for following plugins is available:

• lextudio.restructuredtext : rst syntax highlighting (MIT License)

• swyddfa.esbonio (only release version): linting and live preview (MIT License)

• usernamehw.errorlens: highlights errors and warnings in IDE (MIT License)

The live-preview can then be activated inside a .rst file by pressing “Ctrl + Shift + V” or clicking on the tiny symbol on the top right corner which looks like a book with a magnifier.

If the sphinx configuration is altered the language server has to be restarted:

“Ctrl + Shift + P” and select “Esbonio: Restart Language Server”

If there is any issue with the preview or syntax highlighting the error log can be visualized via the output and select “Esbonio”