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

TOML tables in code-blocks break dynamic functions

Open ubmarco opened this issue 1 year ago • 0 comments

This snippet

.. story:: foo
   :id: ST_FOO
   :status: open

   .. code-block:: toml

      [[project]]
      display_name = "sphinx-needs"

leads to

Traceback (most recent call last):
  File "/home/marco/ub/ubdocs/dist/export/python/virtualenvs/python-default/3.10.14/lib/python3.10/site-packages/sphinx_needs/functions/functions.py", line 396, in _analyze_func_string
    func_name = func_call.func.id
AttributeError: 'Name' object has no attribute 'func'
...
  File "/home/marco/ub/ubdocs/dist/export/python/virtualenvs/python-default/3.10.14/lib/python3.10/site-packages/sphinx_needs/functions/functions.py", line 75, in execute_func
    func_name, func_args, func_kwargs = _analyze_func_string(func_string, need)
  File "/home/marco/ub/ubdocs/dist/export/python/virtualenvs/python-default/3.10.14/lib/python3.10/site-packages/sphinx_needs/functions/functions.py", line 398, in _analyze_func_string
    raise SphinxError(
sphinx.errors.SphinxError: Given dynamic function string is not a valid python call. Got: project

Issue is that sphinx-needs sees [[project]] as a dynamic function call which does not exist. This however is valid TOML https://toml.io/en/v1.0.0#array-of-tables.

2 solutions come to my mind:

  1. global config that deactivates dynamic functions for a certain set of needs
  2. escape mechanism for the [[ ]] syntax
  3. customize start and end tag for the dynamic function delimiters

I'd prefer option 3 as it's simple and safe. Escaping seems tricky as sphinx-needs has to deal with all sorts of other languages that might appear in nested directives.

ubmarco avatar Jun 20 '24 07:06 ubmarco