sphinx-needs icon indicating copy to clipboard operation
sphinx-needs copied to clipboard

count(links) in needs table columns

Open AlbertMietus opened this issue 5 years ago • 2 comments

It would be great to be able to show the NUMBER of incoming/outgoing links in a table.

Now, it is possible to show the links itself; which gives very wide ( & unreadable) tables. Often I'm mostly interested whether there is a (related) need or not; or in how many. The details I can see elsewhere (another table, or in the need itself)

I suggest to have/allow a syntax like: "count( any-ColumnName-that-is-a-list )" for anyplace where any-ColumnName-that-is-a-list is allowed. Whenever the col isn't a list is is useless to count --either raise an exception, or (better?) return 0 This seems simple to implement -- the count functions already exist in python:-)

Note: by this proposal it will work for (the default) links and links_back, and for custom-ones.

Attention: the same syntax should also/mainly work when used as:

.. needttable: 
   :colums: id, title, count(incomming), count(outgoing), outgoing
   ...

Thanks

AlbertMietus avatar Feb 11 '21 10:02 AlbertMietus

Great idea :+1:

Maybe we can make your approach even more generic to allow the definition of python code.

Example:

.. needttable: 
   :colums: id, title, code(len(incoming)), code(if outgoing "Yes" else "No"), outgoing, code(if need("timestamp") < datetime.now() - timedelta(weeks=2) "overdue" else "in time" )
   ...

Maybe we can also reuse the concept of dynamic functions for this. Not sure, but I will update this issue when the concept is in place.

danwos avatar Feb 15 '21 06:02 danwos

Personally, I'm not a fan of allowing code in documentation. Once others thought is was a good idea, introducing all kind of viruses. Let's learn from that! So, no, I do not support the python-body in eg needtables :-) for the same reason. Secondly "writers" are not always good programmers-- it scares them away . And, as I like to convince them to use "Maintainable (technical) Documentation" - like sphinx, needs, plantUML etc. anything that is counterproductive in persuading them, ... Anyhow

Function-alike syntax, like my suggested "count()", is Oke; it not really code. Anything that needs ``eval( and friends)`, "bad". Dynamic functions are IMHO on the edge (but didn't;'t realy need/love/study them; for the same reason

AlbertMietus avatar Feb 16 '21 08:02 AlbertMietus