Support sorting needtable with order of apperance in the document

[chenlijun99]

Hi! First, thanks for Sphinx-needs. It's very cool! Maybe I missed something in the documentation, but is it possible to sort the items in the needtable in the order they appear in the source files? One challenge I see is how to deal with needs coming from multiple files, but maybe something as simple as sort by filename could work?

[chenlijun99]

I see that each need in needs.json already has the docname and doctype properties. Would it be possible to introduce a property like docsrcline? And then support a list of keys instead of a single key for the sort field of needtable.

[danwos]

The idea is good, but I'm not sure if sourceline is a good argument. In a lot of projects, the need objects are stored on different files, get imported by needs.json files and are downloaded from services. Therefore not all of them can be assigned to a source line.

May I ask for your use case, in which sorting by sourceline is a benefit? This helps us to understand all different ways of using Sphinx-Needs much better :)

However, the idea of supporting multiple parameters for :sort: is good and makes totally sense.

[chenlijun99]

Thanks for the reply! My use case is that there is a certain logic order in which I write requirements in a document, where e.g. I start from high-level requirements about the whole system followed by more specific requirements about each part of the system. Finally, for each document I want to include at the top a need table that provides a concise view of all the requirements in the document, with their incoming and outgoing links. I would like the order of the requirements in the table to match the order in which they appear in the document.

[PhilipPartsch]

If you have local written need elements, you can use lineno. Here is an example:

.. needtable:: List of software requirements
   :types: sw_req
   :style: table
   :columns: id; title; docname as "document"; lineno as "line no"
   :sort: lineno

The lineno is more correctly set only with sphinx-needs 2.1.0 with support of embedded needs #1150