Sort needs by the order they were added as outgoing link

[rsarrazin2]

We model test cases and test steps by introducing 2 need types (test_case and test_step). For traceability we :link: the test case with its test steps. For the reader we want to list all test steps below the test cases in the very order they are linked (as the order is relevant).

Example (all types being set to req for the sake of the example):

.. req:: ReqOne
   :id: A_REQ_1
   :status: open
   :links: A_REQ_2, A_REQ_4, A_REQ_3

   .. needtable::
      :filter: "A_REQ_1" in links_back
      :style: table

.. req:: ReqFour
   :id: A_REQ_4
   :status: open

.. req:: ReqThree
   :id: A_REQ_3
   :status: open

.. req:: ReqTwo
   :id: A_REQ_2
   :status: open

The table sorts by :id: (i.e. 2, 3, 4).

Adding :sort: links to the needtable sorts by the order the needs appear (i.e. 4, 3, 2).

How can I have the table sorted in the given order 2, 4, 3?
Or, if this isn't possible or sensible, how can I display the outgoing links in a specific order not only showing their ID but also their title?
Or even further, would you suggest another modelling for test cases and test steps?

Bonus question: What is the difference in needtable between :sort: and :sort_by:? I couldn't grasp it reading the documentation.

Thanks in advance for your answers, and thanks a lot for this nice docs-as-code framework.

[danwos]

I'm afraid, that this is not easily possible.

First of all, Sphinx-Needs wasn't developed to keep the order of elements.
It may be the case in some situations, but there is no guarantee.

Also the used needtable and the filter string have no access to the links value of A_REQ_1 (the "base" need).
The filter algorithm finds 3 need objects, all with one single entry for links_back.
So the filter result is not related to information from the "base" need A_REQ_1.

You could also have 2 "base" objects, which include different orders of links for the same targets.
So though to say which order to take:

.. req:: ReqOne_A
   :id: A_REQ_1_A
   :links: A_REQ_2, A_REQ_4, A_REQ_3

   .. needtable::
      :filter: "A_REQ_1_A" in links_back
      :style: table
   
.. req:: ReqOne_B
   :id: A_REQ_1_B
   :links: A_REQ_4, A_REQ_3, A_REQ_2  # different order

   .. needtable::
      :filter: "A_REQ_1_B" in links_back
      :style: table

The only solution I see is using custom filter code, which is somehow aware of the basic order.
For this you could use https://sphinx-needs.readthedocs.io/en/latest/filter.html#filter-function.

My idea is something like:

index.rst

.. req:: ReqOne
   :id: A_REQ_1
   :status: open
   :links: A_REQ_2, A_REQ_4, A_REQ_3
   :template: req_post  # Can automatically be set by needs_global_options

needs_templates/req_post.need

{content}
   .. needtable::
      :filter-func: my_filters.req_filter({{id}})  #Inject the ID of the "base need
      :style: table

my_filters.py

def req_filter(needs, results, **kwargs):
    """Searches for needs defined by the links of a given "base" need". Respects link-order. """
    base_need_id = kwargs["arg1"]
    base_need = needs[base_need_id]
    base_need_links = base_need['links']
    
    for link in base_need_links:
        if link in needs:
            results.append(needs[links])  

⚠ The above code is untested and I'm not 100% sure if the order of the returned filter-function result is kept.

Let me know if this idea works for you and how your final solutions looks like.

Or even further, would you suggest another modelling for test cases and test steps?

No, I like the approach as the step-order is defined in one need and this makes it easy for the user to maintain it.
In some projects I created a step-chain by adding the next-step as link to each prior step. But this makes the steps not really reusable. So, you already have a good solution 👍.

Bonus question: What is the difference in needtable between :sort: and :sort_by:? I couldn't grasp it reading the documentation.

Wasn't aware that we have these two options.
I guess sort is somehow an "old" implementation, introduced for needtables only, before we added a generic approach and config for all filter-related directives. Should be removed someday.

[rsarrazin2]

Thanks for all the input. For quick tests, I went for Filter code rather than Filter function.

I tested the following (using a dict as I would else get exception: list indices must be integers or slices, not str):

      needs_dict = {x['id']: x for x in needs}
      base_need_id = "A_REQ_1"
      base_need = needs_dict[base_need_id]
      base_need_links = base_need['links']
      
      for link in base_need_links:
         results.append(needs_dict[link])

which gave a sorted result.

Going for the following:

      needs_dict = {x['id']: x for x in needs}
      results.append(needs_dict["A_REQ_2"])
      results.append(needs_dict["A_REQ_4"])
      results.append(needs_dict["A_REQ_3"])

I eventually found out that results are always sorted by ID (this appears as 2, 3, 4). Is there a way to tell the framework not to sort at all?

[danwos]

Is there a way to tell the framework not to sort at all?

If afraid not.
Shouldn't be much effort to allow this somehow in the code. I guess we only need to deactivate the default value for sort.

[rsarrazin2]

For backwards compatibility, it might be better to add a new sort option no_sort while keeping the ID sort as default as it is now.