Dynamic function: parse return value as rst

Hi, I’m trying to add user defined dynamic function which returns string in rst format. What I was trying to do is to call that function inside a need and hopefully to have the function return value rendered in the need as rst.

Here is a simplified example to illustrate:

# conf.py

def test_rst_rendering(app, need, needs):
   """Here we're returning a string which in rst should be bold"""

    return "**This should be bold**"

def test_need_content(app, need, needs):
   """And here we're testing if possible to update need content in the function with rst syntax"""

    need["content"] = "**This should be bold**" + need["content"]
    return "content"

needs_functions = [
    test_need_content,
    test_rst_rendering,
]

And when used with our own need_type (maybe we have to somehow configure our custom need type in order to dynamically render rst from function return value):

class Example:
    """
    .. output:: Example
        :id: OUTPUT_100
        :tags: example

        [[test_need_content()]]
        [[test_rst_rendering()]]
    """

What we end up is that none of the functions resulted in rendering output as rst. So trying to modify need content also didn’t work:

I was able to see in implementation where the function call is replaced with the return value and that it’s executed in the process_need_nodes.

Does anybody maybe know if something like this is possible to do? Am I maybe missing something out, some config which is not set in order this to work?

***I’m using version sphinxcontrib-needs==0.6.0

Many thanks!

[danwos]

I think this is not possible right now. 2 Reasons:

1. The rst-rendering is done by Sphinx before the dynamic functions get executed.
2. dynamic functions mostly do a simple string-replacement: func-call out, return value in. And that directly on the already rendered docutils nodes.

There would be a way to treat the return value as rst and render it (basic rst only, no sphinx directive support). But then Sphinx-Needs would need to deal with a small docutils node-tree and inject this somehow in the already existing node-tree of the content area. So .e.g a simple text-node with a dynamic function must get split and the rendered rst-tree somehow integrated. Possible, but I have the feeling that this would have a lot of corner cases.

Templates are also my suggested workaround. There are executed earlier. Drawback: No direct python/script support for dynamic data. But maybe you could inject a Jinja-statement into the Jinja-Environment and then calculate your values. Maybe this stackoverflow question about jinja and custom python function is a good starter.

However, please keep me updated, if you find a solution for your case. I would be happy to document it and share it with our community.

[twodrops]

@krivi95 Not a solution for the above behavior but is templates a solution for this usecase you have?