IDE Support

Features

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

Auto-generated IDs
card-img-bottom
Snippets
card-img-bottom
ID Selection
card-img-bottom
Goto Definition
card-img-bottom
Need Preview
card-img-bottom

Installation

VsCode

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.

Usage

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 conf.py. 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

../_images/lsp_auto_ids.gif

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

Hint

  • 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

../_images/lsp_snippets.gif

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

ID Selection

../_images/lsp_id_selection.gif

  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

../_images/lsp_goto.gif

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

../_images/lsp_preview.gif

Move the mouse cursor over any need ID

MyST/Markdown

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

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

Usage

  • 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 conf.py 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. myfile.md:

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

Example

Directive snippets

../_images/lsp_directive_snippets_markdown.gif

Directive snippets used inside {eval-rst} block

../_images/lsp_directive_snippets_inside_eval_rst_block_markdown.gif

Role need completion

../_images/lsp_need_role_need_suggestion_markdown.gif