needimport¶

Added in version 0.1.33.

needimport allows the import of needs from a JSON file.

You can generate a valid file using the builder needs, for example:

.. needimport:: needs.json
   :id_prefix: imp_
   :version: 1.0
   :tags: imported;external
   :hide:
   :collapse:
   :filter: "test" in tags
   :template: template.rst
   :pre_template: pre_template.rst
   :post_template: post_template.rst
   :allow_type_coercion: true
   :parse_by_doctype: true

The directive argument can be one of the following formats:

A remote URL from which to download the needs.json:

.. needimport:: https://my_company.com/docs/remote-needs.json

A file:// URL, which is read as a URL (as needs_external_needs reads a json_url):
```
.. needimport:: file:///absolute/path/to/needs.json
```
A local path relative to the containing document:
```
.. needimport:: needs.json
```
A local path starting with / is relative to the Sphinx source directory:
```
.. needimport:: /path/to/needs.json
```
For an absolute path on Linux/OSX, make sure to start with two //:
```
.. needimport:: //absolute/path/to/needs.json
```
For an absolute path on Windows, just use the normal drive letters with either forward or backward slashes:
```
.. needimport:: c:/absolute/path/to/needs.json

.. needimport:: c:\absolute\path\to\needs.json
```

The key of each need in the file is its id: a need whose id differs from its key is imported under its key, with a needs.needimport warning. needs_id_regex is not applied to imported needs. A file that cannot be read – missing, not downloaded, not valid JSON, or without the version asked for – is one needs.needimport warning at the directive, and the directive imports nothing; the build goes on. A local file that is missing is read on the next incremental build once it exists.

A value the file leaves out (needs_json_remove_defaults) is restored from the file’s own needs_schema, the default of the field in the project that wrote it, not from this project’s declarations: a need type’s default here does not fill it. This project’s defaults fill only a field to which the file’s schema gives no default.

Note

If you are rebuilding documentation incrementally (for example, when using sphinx-autobuild), Sphinx automatically detects changes to the local JSON files. However, with remote URLs or a file:// URL, you must run a Sphinx build with the -E flag to rebuild the environment from scratch when the remote file changes.

Options¶

id_prefix¶

You can set :id_prefix to add a prefix in front of all imported need ids. This may be useful to avoid duplicated ids.

Note

The ids of the file are its namespace, and the prefix is that namespace’s name. The file owns the ids it contains: a reference to one of them – a link field, or the id written in a need’s content – gets the prefix whether that need is imported or not (:ids: and :filter: leaving it out change nothing); a link given as a string that holds a dynamic function or a variant is left as written. A reference to an id the file does not contain is left as it is, and may resolve to a need of the importing project. So the importing project references the imported needs by their prefixed ids, and a reference rewritten to a need that is not imported with the same prefix is a dead link (needs.link_outgoing for a link field, needs.link_ref for a :need: role in the content).

The content is opaque markup: every occurrence of a file id as a whole word is rewritten, inside code blocks and file names too; an id inside a longer word is left as it is.

version¶

You can specify a specific version for the import using the :version: option. This version must exist inside the imported file.

If no version is given, we use the current_version attribute from the JSON file. In most cases this should be the latest available version.

tags¶

You can attach tags to existing tags of imported needs using the :tags: option (as a comma-separated list). This may be useful to mark easily imported needs and to create specialised filters for them.

ids¶

Added in version 4.0.0.

You can use the :ids: option to import only the needs with the given ids (as a comma-separated list). This is useful if you want to import only a subset of the needs from the JSON file. An id the file has no need for is named in one needs.needimport warning.

filter¶

You can use the :filter: option to imports only the needs which pass the filter criteria. This is a string that is evaluated as a Python expression, it is less performant than the :ids: option, but more flexible.

Please read Filtering needs for more information. A filter that fails is one needs.needimport warning for the directive. It reads each record of the file, not a need of this build, so the c.source facets (Filtering by where a need comes from (c.source)) are not available in it: a facet read there is reported as not available in a needimport filter.

hide¶

You can use the :hide: option to set the hide tag for all imported needs. So they are not rendered on the page.

collapse¶

The :collapse: will hide the meta-data information by default, if set to True. See also collapse description of need items.

Note

Imported needs support conditional links. Link strings in the JSON file can contain conditions, e.g. "links": ["REQ_001[status==\"open\"]"], and these conditions will be evaluated against the target needs during the build.

Warning

Imported needs may use different need types as the current project.
The sphinx project owner is responsible for a correct configuration for internal and external needs.
There is no automatic type transformation during an import.

allow_type_coercion¶

Added in version 6.1.1.

Allows to enable or disable type coercion of fields for each need, and parsing of dynamic functions. For example if the tags need field is provided as a string like "tag1,tag2,[[func()]]", it will be parsed only if this option is set to True, otherwise will fail.

This option defaults to True.

parse_by_doctype¶

Added in version 9.0.0.

Parses each imported need’s content in the markup its doctype names, rather than in the markup of the page the needimport is written in. A needs.json written by Sphinx-Needs records the suffix of the page a need was written in (or the markup its content declared), omitting .rst under needs_json_remove_defaults, where the file’s schema restores it; so Markdown exported from a MyST page renders as Markdown in a reStructuredText page, and reStructuredText exported from a reStructuredText page renders as such in a MyST page. The suffix must be one this project’s source_suffix maps to a reStructuredText or a MyST parser (as for content written in another markup); a need with no doctype, or an empty one, is parsed in the page’s markup (and one with none records the page’s suffix, as any need that declares none).

A need whose content is parsed in its doctype keeps that doctype, and the warnings raised while parsing it name the directive’s line plus the line of the content they are on. Content that stays in the page’s markup (no or an empty doctype, one this project cannot parse, a templated need) is reported as before – in a MyST page at about twice the directive’s line (issue #2144).

:parse_by_doctype: alone (or true) turns this on for one import, and :parse_by_doctype: false turns it off; without the option, needs_import_parse_by_doctype decides.

A need rendered through a template – its record’s template, the :template: option, or a template the project gives through needs_fields (a default, or any predicates) – is parsed in the page’s markup, template and content together: the template is a file of the importing project, written in its pages’ markup. A predicate is decided only when the need is created, so a project with any template predicate parses every imported need in the page’s markup, also one that no predicate matches. pre_template and post_template are always parsed in the page’s markup. Content with jinja_content is rendered by Jinja first, and then parsed in its doctype.

If this project cannot parse a doctype – .md without myst-parser, or a suffix that is not in source_suffix – the content of those needs is parsed in the page’s markup and they are imported as before, and one needs.import_doctype warning per directive names that doctype (none if none of those needs has content, or all of them are hidden by their record or by :hide:). Register the suffix, set :parse_by_doctype: false, or add "needs.import_doctype" to suppress_warnings.

The imported content is not restricted: what Content written in another markup says content from another markup should not contain holds here too.

Customization¶

The following options can be set, which overwrite the related options in the imported need itself. So you can decide what kind of layout or style to use during import.

layout
style
template
pre_template
post_template

Global keys¶

Added in version 4.2.0.

The needs_import_keys configuration can be used to set global keys for use as the directive arguments.

For example:

needs_import_keys = {"my_key": "path/to/needs.json"}

Allows for the use of:

.. needimport:: my_key