Runtime error when defining Sphinx tag

[marcel-22]

Expected behavior

A custom CSS is used to improve the Sphinx layout during HTML preview. To enable this CSS the Sphinx tag preview is defined in Esbonio workspace settings. The old setting was "esbonio.sphinx.tags": ["preview"], which I transformed into "esbonio.sphinx.buildCommand": ["-t preview"].

Actual behavior

When I use the new setting "esbonio.sphinx.buildCommand": ["-t abc"], Esbonio produces a runtime error. Note that I replaced preview with abc to make sure the problem is not caused by enabling the CSS stylesheet.

Is our buildCommand definition correct?

Log output

[esbonio.Configuration] CompletionConfig(preferred_insert_behavior='replace')
[esbonio.Configuration] Previous: CompletionConfig(preferred_insert_behavior='replace')
[esbonio.Configuration] Current: CompletionConfig(preferred_insert_behavior='replace')
[esbonio.Configuration] File scope: ''
[esbonio.Configuration] Workspace scope: 'file:///c%3A/git/sigma'
[esbonio.Configuration] Resolved config: {
  "pythonPath": [],
  "pythonCommand": [
    ".venv\\Scripts\\python.exe"
  ],
  "enableDevTools": false,
  "buildCommand": [
    "-t abc"
  ]
}
[esbonio.Configuration] SphinxConfig(enable_dev_tools=False, python_command=['.venv\\Scripts\\python.exe'], build_command=['-t abc'], env_passthrough=[], cwd='', python_path=[])
[esbonio.Configuration] Previous: SphinxConfig(enable_dev_tools=False, python_command=['.venv\\Scripts\\python.exe'], build_command=['-t abc'], env_passthrough=[], cwd='', python_path=[])
[esbonio.Configuration] Current: SphinxConfig(enable_dev_tools=False, python_command=['.venv\\Scripts\\python.exe'], build_command=['-t abc'], env_passthrough=[], cwd='', python_path=[])
[esbonio.Configuration] File scope: ''
[esbonio.Configuration] Workspace scope: ''
[esbonio.Configuration] Resolved config: {
  "config": {},
  "level": "debug",
  "window": false,
  "stderr": true
}
[esbonio.Configuration] LoggingConfig(level='debug', format='[%(name)s] %(message)s', filepath=None, stderr=True, window=False, config={}, show_deprecation_warnings=False)
[esbonio.Configuration] Previous: LoggingConfig(level='debug', format='[%(name)s] %(message)s', filepath=None, stderr=True, window=False, config={}, show_deprecation_warnings=False)
[esbonio.Configuration] Current: LoggingConfig(level='debug', format='[%(name)s] %(message)s', filepath=None, stderr=True, window=False, config={}, show_deprecation_warnings=False)
[esbonio.Configuration] File scope: ''
[esbonio.Configuration] Workspace scope: ''
[esbonio.Configuration] Resolved config: {
  "showLineMarkers": false
}
[esbonio.Configuration] PreviewConfig(bind='localhost', http_port=0, ws_port=0, show_line_markers=False)
[esbonio.Configuration] Previous: PreviewConfig(bind='localhost', http_port=0, ws_port=0, show_line_markers=False)
[esbonio.Configuration] Current: PreviewConfig(bind='localhost', http_port=0, ws_port=0, show_line_markers=False)
[esbonio.Configuration] File scope: ''
[esbonio.Configuration] Workspace scope: ''
[esbonio.Configuration] Resolved config: {
  "preferredInsertBehavior": "replace"
}
[esbonio.Configuration] CompletionConfig(preferred_insert_behavior='replace')
[esbonio.Configuration] Previous: CompletionConfig(preferred_insert_behavior='replace')
[esbonio.Configuration] Current: CompletionConfig(preferred_insert_behavior='replace')
[esbonio.Configuration] File scope: ''
[esbonio.Configuration] Workspace scope: ''
[esbonio.Configuration] Resolved config: {
  "preferredInsertBehavior": "replace"
}
[esbonio.Configuration] CompletionConfig(preferred_insert_behavior='replace')
[esbonio.Configuration] Previous: CompletionConfig(preferred_insert_behavior='replace')
[esbonio.Configuration] Current: CompletionConfig(preferred_insert_behavior='replace')
[esbonio.Configuration] File scope: ''
[esbonio.Configuration] Workspace scope: ''
[esbonio.Configuration] Resolved config: {
  "preferredInsertBehavior": "replace"
}
[esbonio.Configuration] CompletionConfig(preferred_insert_behavior='replace')
[esbonio.Configuration] Previous: CompletionConfig(preferred_insert_behavior='replace')
[esbonio.Configuration] Current: CompletionConfig(preferred_insert_behavior='replace')
[esbonio.Configuration] File scope: ''
[esbonio.Configuration] Workspace scope: ''
[esbonio.Configuration] Resolved config: {
  "preferredInsertBehavior": "replace"
}
[esbonio.Configuration] CompletionConfig(preferred_insert_behavior='replace')
[esbonio.Configuration] Previous: CompletionConfig(preferred_insert_behavior='replace')
[esbonio.Configuration] Current: CompletionConfig(preferred_insert_behavior='replace')
[esbonio] Task finished: <Task finished name='Task-18' coro=<PreviewManager.show_preview_uri() done, defined at c:\Users\...\.vscode\extensions\swyddfa.esbonio-0.94.2\bundled\libs\esbonio\server\features\preview_manager\__init__.py:183> result=None>
usage: __main__.py [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]
__main__.py: error: the following arguments are required: SOURCE_DIR, OUTPUT_DIR, filenames
[esbonio.SphinxManager] SphinxClient[e80452f9-d59a-4a5d-822f-20e5b7320363]: ClientState.Starting -> ClientState.Errored
[esbonio.SphinxManager] sphinx-agent process exited with code: 2
[esbonio.SphinxManager] Stderr:

[esbonio.SphinxManager] Cancelled future '<Future at 0x2455bb97b90 state=cancelled>' for pending request 'c12eccab-89d0-4ae1-a586-62ccc30072dd'
[client] sphinx/clientErrored: {
  "id": "e80452f9-d59a-4a5d-822f-20e5b7320363",
  "error": "RuntimeError: 2",
  "detail": "RuntimeError: 2\n"
}

(Optional) Settings from conf.py

No response

[alcarney]

Is our buildCommand definition correct?

Unfortunately not.

esbonio.sphinx.buildCommand should be set to whatever sphinx-build command you would run if you were to build your docs outside of esbonio e.g. ["sphinx-build", "-M", "html", "<src>", "<dest>", "-t", "preview"]

(Ideally, the server should be doing more here to help you get to the right value - #781)

[marcel-22]

Ah, thanks, I was not sure how to define the buildCommand and could not find an example either. I adjusted the definition and now it's working fine!

Normally we are running sphinx-build -M html docs docs/_build -W --keep-going $@. Do you advise to include the options -W --keep-going to esbonio.sphinx.buildCommand ?

[alcarney]

Glad to hear you managed to get it working!

Do you advise to include the options -W --keep-going to esbonio.sphinx.buildCommand ?

If that's the way you normally build your docs it's definitely worth trying so that you get consistent behavior both with and without esbonio. The server now uses Sphinx's cli parser so in theory should be able to support (almost*) all valid sphinx-build arguments.

* The only exceptions are those that don't make sense in the language server context - such as --color or -P (starting pdb on exceptions)

[marcel-22]

Thanks for your reply. I'll close this issue since it's resolved.