Feature ideas and their priority

[danwos]

This Discussion is for introducing "game changing" feature ideas, before a real technical discussion is started.

Please introduce one feature per post and with the following information:

• Summary
• Description
• use cases, where this feature would really help
• Link to an issue, which stores a technical concept (optional)

Users are free to vote for them, so that we can get a feeling about what is really needed.

[danwos]

Idea: Referencing need-objects from other documents

Needs in sphinx project A shall be able to reference needs in sphinx project B.
It's somehow similar to the intersphinx feature.

In big companies sphinx project can get really huge and hundreds of developers may provide content.
Therefore the sphinx build time is huge, too huge for local build and tests.
So sphinx projects get often separated into smaller projects, but overall they still need to be connected.
There are also scenarios where multiple standalone sphinx projects get merged to a single project automatically for each new product release.

It would be great, if specifications from a sphinx documentation for sw development are able to reference/link external requirements from a sphinx requirement documentation.

Ticket: #137

[danwos]

Idea: Needs Viewer App (JavaScript)

A JavaScript based App shall load and present all needs from one or multiple needs.json files.
It shall support searching, filtering, linking and presenting all needs at a common place.

The app shall be integrated into a sphinx-documentation via a collapsible sidebar.
First, rough mockup:

Benefits:
Readers of the documentation will be able to search for needs on their own.
Right now the author needs to provide certain tables or the user needs to use the common text-based sphinx search field.

A huge project can have multiple sphinx-projects, which all produces needs.json files.
Each documentation can load and present the overall amount of need-objects from all sub-projects in their documentation and even link to them (see request #137).

Links to needs can show a hover-popup, which shows basic information about the need.
Like github does this also with numbers like #220. (see request #220)

Ticket: TBD

Involved/Linked Tickets: #137 , #220

Technical realization / components:

• needs.json js-importer and data-storage (local and external sources)
• search api/functions (js)
• link-hover component
• Needs-App user interface
• needs.json builder may need to export some extra data:
  • need file-path (for generating later links)
  • First x chars of generated content (no rst, no html)

[jakehader]

Idea: Custom id generator within add_need.

@danwos

When using the sphinx-needs package I am looking to insert a .. test:: directive into the docstring of a unit test. It would be nice to be able to create the id based on some other attribute of the need. Specifically, I am looking to match the id to the unit test method name automatically without requiring manual duplication of the information (in both the method name and in the id).

Having the requirements and test names be human-readable is helpful for documentation and requirements traceability review.

The code I am looking at is:

https://github.com/useblocks/sphinxcontrib-needs/blob/166f35fa4dbf3dcf111d4e9c394774bf9f067947/sphinxcontrib/needs/api/need.py#L125-L128

I would try to override the implementation of make_hashed_id in my own project, but I would like to also have access to all the args/kwargs being passed into add_need to be able to customize that behavior.

Is this something that is reasonable to implement and in-line with the direction of the project?

[jakehader]

Note: this might be related to some of the on-going work in #201 by @danieleades.

[danwos]

I like the idea and maybe we should have a config var, which takes a function.
If set, make_hashed_id gets replaced.
Ohh, I think we also need to have some filter logic, as the function shall replace make_hashed_id for some specific types only.

And for sure, it must get all available need data.

But I'm not sure, if reusing the unit test name automatically will work. Thought about it already in the past and haven't found any solution.
But I really hope you find it :) would be an awesome, time saving feature.

[jakehader]

I noticed that I have a signature attribute in the need dictionary which corresponds to the unit test name so that's where I got the idea from. That might not be intended purpose or "right way" to do it. Either way, having some type of customizable id generator could be separate.

I will try to test it out on my own and put together a PR if I get somewhere that makes sense.

[danwos]

You are right, I totally forgot the signature, which gets set by automodule and is already used.
Now I remember and yes, it was added exactly to get the unit test name.
But I'm not sure if this information is already available, when it comes to the point to set an id.
Because the id gets set really early in the process (when Sphinx visits the need-directive) and the signature seems to be collected later (event doctree-resolved)