Is it possible to reference needs with intersphinx? / Add intersphinx support

As the title says I’d like to know if it is possible to cross reference using intersphinx.

As a try out I tried adding the following to conf.py

extensions = [
  "sphinx.ext.intersphinx",
]

intersphinx_mapping = {
  'need': (
    'https://sphinxcontrib-needs.readthedocs.io/en/latest/',
     None
  )
}

and referencing using

:need:`:need:SPEC-1`

or

:need:`SPEC-1`

(SPEC-1 is defined on the front page of the documentation), but no such luck. Has anybody tried this?

[danwos]

The last days I have thought a lot about this feature and how to implement it. My proposal is to not support intersphinx but to provide another mechanism, which allows the same behavior: Getting links to external needs into your document.

It would be great, if you could give me your opinion, if it covers your case.

Reason why not using intersphinx

1. I have no idea how to do it 😉
2. The intersphinx mechanism would not support other use cases, like getting additional data from external needs, showing external needs in tables or flows, using their data in dynamic functions…
3. We already have the needs builder for exporting data, so this part is already done.

Long-term goals of the new concept

1. Getting links to external needs
2. Showing external needs in tables and flows This includes being able to filter on their data!
3. Giving access to their data for dynamic functions and co.

Why not using needimport?

needimport creates a copy of external needs so that they become internal and are not linked to external resources anymore.

New concept

New conf-option needs_intersphinx

needs_intersphinx = [
  ('http://mydocs/my_project', 'http://mydocs/my_project/needs.json', '1.0'),
  ('http://mydocs/another_project/', 'http://mydocs/another_project/data/exports/needs.json', '2..5'),
  'http://docs.com/simple_project'
]

needs_intersphinx takes a list of tuples which define:

• An url/path to use as root-path for external links
• An url/path to an external needs.json file
• A specific version to read (if not give, latest is used)

The first option can also be given as single string. In this case the needs.json must be stored on root level and the version is automatically set to latest.

New conf-option needs_autoexport

needs_autoexport = True

If set to True, the functions to build a needs.json file will be called even if other builders are used, e.g. html. In this case it is easy to always provide a needs.json file without caring about to call the needs builder.

Update of need-role

The need-role will search for a given ID in this order:

1. internal needs
2. external needs

If an id is found in the external needs, a link to the exact location in the external documentation is generated.

New need-value: doc_path

The needs.json does not store any information, in which document the need can be found. This must be changed by adding a new, automatically calculated option to the internal need-dict: doc_path. This value stores the path relative to the doc-root folder (conf.py location)

Suggested behavior

During a build, all need.json files given by needs_intersphinx will get downloaded and internally imported as standalone information (no link to the internal needs). Beside the role :need: there will be no way to work with this data (for now)

Drawbacks

• IDs should be unique. This must cover the internal needs and all external needs.
• A build will always need an internet connection, if needs.json files needs to be imported. (But i think this drawback also intersphinx has.)
• Big needs.json files may need some time to be downloaded.

So, any ideas/feedback about this concept? Will it work for your cases?

[twodrops]

@danwos I did a quick test of the feature branch. I couldn’t wait long to test it out 😃 The feature is really cool 🥇

Two issues I quickly noticed:

Issue 1 The second build after a successful first build always fails with the following error:

A need with ID REQ_xxxxxxx already exists! This is not allowed.

A “clean” build or the “third build” succeeds.

Issue 2 The needs in the externel json appears correctly (for example, in a needtable). If the imported need is referred elsewhere, the need ID does not appear in the need that references it.