Nested needs: automatic IDs for children

[danwos]

IDs can be generated based on the title (hash) or must be set.

If needs are nested in other needs, it makes sense to somehow inherit the id from the parent need. Example: parent need id: req_123 (requirement) child need 1 id: req_123_a (spec) child need 2 id: req_123_b (spec)

This can't be done by dynamic function, as ids must be set very early (reading in all needs). All other actions (dynamic functions, fetching parent needs) are done later, after all needs got already read in and stored under their specific id.

An idea is to provide 2-3 specific id functions, which get executed directly. These functions are very limited, as not all needs got already read in (and all the other stuff). But they could give access to data from the need itself and from parent needs (if sphinx reads them in the right order).

function ideas:

• spec_1_<<option>>: gets replace by the current option. E.g. spec_1_<<author>> -> spec_1_mr_black.
• <<parent:option>>_a: gets replaced by id of first parent. E.g. <<parent:id>>_spec -> req_123_spec.

[Thomas-Swindells-t]

I've started working on some code to do this which I hope to finish and be able to contribute soon.

The basic concept will be to provide an option to select the id generator function.

make_hashed_id: the current and default function make_hashed_id_include_parent: creates a hashed id prefixed by the parent (parentId.hashedchild) make_inherited_id: If a full id is specified that is used, if the provided id starts with a "." then it is appended to the parent (or docname). This would allow defining "child:: xxx id: .foo" and get a unique deterministic name make_indexed_id: A specialization of the inherited_id which will automatically generate an id in the format . where position is the need index under its parent (counting all needs) make_type_indexed_id: A specialization of the inherited_id which will automatically generate an id in the format . where position is the index under its parent counting needs of only the same type.

The last is likely to be the most useful, it allows you to give the need an explicit full id, a partial id, or an autogenerated id that is stable as long as you don't insert a need of the same type above it, but still lets you add other needs types above it without impacting the generated id.

[danwos]

Sounds promising and I'm looking forward for the PR :)

I like most make_inherited_id, as it only combines two given ids (parent + child) without generating something.

As I'm writing mostly docs for automotive tools and bigger teams, ID generation is often problematic, as the ID can change quite fast. Typo in the title? And bang: new ID and links are no longer valid. So in our documentation "id generation" is always turned off. (For sure there may be smarter ways to generate a stable but unique id)

Selecting it by an option is fine for me. But please put is also to the list of not printed options, so that it is not shown by default. I think it contains more a technical configuration and not some important info for the docs. Tell me, if I'm wrong. And for sure it still can be printed by defining a custom layout.

And finally, thanks already for your commitment :+1: