Fix config option definition

code/changes/1074.fix.md

@@ -0,0 +1 @@
+VSCode will no longer incorrectly mark the simple form of `esbonio.sphinx.pythonCommand` as an error.

code/package.json

@@ -199,23 +199,33 @@
                     },
                     "esbonio.sphinx.pythonCommand": {
                         "scope": "resource",
-                        "type": "object",
-                        "default": null,
                         "description": "Instructions on how to launch the background Sphinx process for the project",
-                        "properties": {
-                            "command": {
+                        "default": null,
+                        "oneOf": [
+                            {
                                 "type": "array",
-                                "description": "The Python command to use when launching the background Sphinx process."
-                            },
-                            "cwd": {
-                                "type": "string",
-                                "description": "The working directory in which to launch the background Sphinx process."
+                                "items": {
+                                    "type": "string"
+                                }
                             },
-                            "env": {
+                            {
                                 "type": "object",
-                                "description": "Environment variables to set/override for the background Sphinx process."
+                                "properties": {
+                                    "command": {
+                                        "type": "array",
+                                        "description": "The Python command to use when launching the background Sphinx process."
+                                    },
+                                    "cwd": {
+                                        "type": "string",
+                                        "description": "The working directory in which to launch the background Sphinx process."
+                                    },
+                                    "env": {
+                                        "type": "object",
+                                        "description": "Environment variables to set/override for the background Sphinx process."
+                                    }
+                                }
                             }
-                        }
+                        ]
                     }
                 }
             },

docs/usage/howto/configure-the-sphinx-build-env.rst

@@ -208,6 +208,21 @@ Advanced Usage
 There are situations where you might need more control over how the background Sphinx process is launched.
 In which case :esbonio:conf:`esbonio.sphinx.pythonCommand` accepts an object allowing you to provide additional information.
 
+.. warning::
+
+   If you use the VSCode extension, when using this expanded configuration format, you **must** provide a value for the ``PYTHONPATH`` environment variable (even if it is empty).
+   Otherwise the extension's fallback environment will take priority over your intended environment and will lead to unexpected results.
+
+   Example config:
+
+   .. code-block:: toml
+
+      [tool.esbonio.sphinx.pythonCommand]
+      command = ["uv", "run", "python"]
+      env = { PYTHONPATH = "", MY_ENV_VAR = "value" }
+
+   See `this issue <https://github.com/swyddfa/esbonio/issues/1074>`__ for more details.
+
 Environment Variables
 ^^^^^^^^^^^^^^^^^^^^^
 

lib/esbonio/changes/1074.fix.md

@@ -0,0 +1 @@
+Document edge case when using the advanced form of `esbonio.sphinx.pythonCommand` together with the VSCode extension (or any client that provides a fallback configuration via `initializationOptions`).