Hacking the Source Code

By Lex Li

Build from source

  1. Clone the repo to a local path such as /Users/someuser/vscode-restructuredtext.

  2. Navigate to this folder.

  3. Resolve Node.js dependencies via yarn install .

  4. Build via yarn compile .

  5. Configure Sphinx following Configuration .

  6. Run VS Code from this folder via code . .

  7. In this editing VS Code instance, press F5 to start a debugging instance.

cd /Users/someuser
git clone https://github.com/vscode-restructuredtext/vscode-restructuredtext.git
cd vscode-restructuredtext
yarn install
yarn compile
code .

Note

To configure the code command, please follow this guide .

You can now open a test folder in this debugging instance.

Debugging with Esbonio

To debug the language server, clone its source code from GitHub,

cd /Users/someuser
git clone https://github.com/swyddfa/esbonio.git

and then edit the settings of the test folder to include Esbonio source folder,

{
    "esbonio.server.sourceFolder": "/Users/someuser/esbonio/lib/esbonio",
    "esbonio.server.debugLaunch": false
}

Now restart the VSCode instance being debugged, so that the extension picks up this change and prepares the debugging environment by removing installed esbonio package and loading esbonio from the source with debugpy enabled for debugging.

Note

If everything is configured properly, you should see debugpy is at port 5678. Connect and debug.

Note

If you want to debug initialization, then change esbonio.server.debugLaunch to true.

Then launch another VSCode instance and open esbonio source folder in it.

Make sure its launch.json contains the following profile,

{
    "configurations": [
        {
            "name": "Python: Remote Attach",
            "type": "python",
            "request": "attach",
            "connect": {
                "host": "localhost",
                "port": 5678
            },
            "pathMappings": [
                {
                    "localRoot": "${workspaceFolder}/lib/esbonio",
                    "remoteRoot": "."
                }
            ]
        }
    ]
}

Start debugging with Python: Remote Attach profile and this VSCode instance will attach to the language server via port 5678. All debugging features like break points should work.

Publish to Marketplace

To publish this extension, use vsce .

cd /Users/someuser
git clone https://github.com/vscode-restructuredtext/vscode-restructuredtext.git
cd vscode-restructuredtext
vsce publish