IDE Support


The following features are supported when using an Esbonio based IDE extension, like VsCode extension reStructuredText, in your Sphinx-Needs project.

Auto-generated IDs
ID Selection
Goto Definition
Need Preview



The VsCode extension reStructuredText supports all the Sphinx-Needs language features and is available at Visual Studio Marketplace.

To install and configure this extension, see details in How to install reStructuredText from Marketplace and

How to use it.


To use all the Sphinx-Needs language featues,

  1. Install IDE extension or plugin, see current supported IDE extension in Installation.

  2. Build needs.json file in your Sphinx-Needs project:

    • automatically build needs.json if configure needs_build_json = True in See details in needs_build_json.

    • manually build needs.json using sphinx-build -b needs source_dir build_dir. See details in Builders.

Auto-generated need IDs


Type : in the line directly below a need directive like .. req:: and select :id: in the IntelliSense interface.


  • If needls can’t detect the type of the need it will just output ID.

  • The ID is calculated using a hash function of the current user, doc URI, line number and the need prefix (e.g.). To lower the risk of ID conflicts further a pseudo-randomization is part of the ID generation.s

Predefined Snippets


Type .. and choose to auto-complete the directive in the IntelliSense interface.

ID Selection

  1. After :need: role or :links: option type -> which triggers the auto-completion of needs

  2. Select a need type from the IntelliSense dialog (use arrow keys)

    • Type > again to trigger the doc completion (file in which needs are specified)

    • Type / to complete the doc path, continue until the doc path is completed to a *.rst file

    • Type > to trigger completion of a specfic need by ID, expand the completion item info to see the content of the selected need

Goto Definition for need IDs


Move cursor to a need ID and hit F12

Alternatively right click on a need ID and choose “Go to Definition” from the context menu

Need information on mouse hover


Move the mouse cursor over any need ID


Directives and roles can be used in MyST in this Syntax.

All the above IDE Features can also be supported for MyST/Markdown.


  • Install MyST Parser using pip.

    pip install myst-parser
  • Enable and active the MyST Parser extension in your Sphinx-Needs project by simply adding the following in your file:

    extensions = ["sphinx_needs", "myst_parser"]
    source_suffix = [".rst", ".md"]
  • All the above IDE Features are supported and used the same way like editing in rst files from above Usage, when you editing your markdown files. e.g.

    • Directive snippets and role completion will be automatically translated into MyST/Markdown supported syntax style, see the following Example


Directive snippets


Directive snippets used inside {eval-rst} block


Role need completion