Fix usage of reST syntax in prefix parameter of meta (#1046)

The usage of the `prefix` parameter of the `meta` layout function (as
per the docs) does not work. There are two problems with this:

1. The documentation for `meta` does not mention that backslashes need
to be escaped and shows unescaped backslashes instead. The docs for
`meta_all` do not make this mistake.
2. [Since version
0.16](https://docutils.sourceforge.io/HISTORY.html#release-0-16-2020-01-16),
docutils inserts null-characters when parsing escaped backslashes, which
in turn is not accepted by
[`ast.parse`](https://docs.python.org/3/library/ast.html#ast.parse). The
solution is described in the [release notes for docutils
0.16](https://docutils.sourceforge.io/HISTORY.html#release-0-16-2020-01-16):
Using `node.astext()` instead of `str(node)`

AUTHORS

@@ -37,3 +37,5 @@ Duodu Randy <duodurandy19@gmail.com>
 Christian Wappler <chri.wapp@gmail.com>
 
 Chris Sewell <chrisj_sewell@hotmail.com>
+
+Simon Leiner <simon@leiner.me>

sphinx_needs/layout.py

@@ -397,7 +397,7 @@ def _func_replace(self, section_nodes: List[nodes.Node]) -> List[nodes.Node]:
                     node.replace(child, new_child)  # type: ignore[attr-defined]
                 return_nodes.append(node)
             else:
-                node_str = str(node)
+                node_str = node.astext()
                 # func_elements = re.findall(r'<<([a-z_()]*)>>', node_str)
                 node_line = nodes.inline()
 
@@ -486,7 +486,11 @@ def meta(self, name: str, prefix: Optional[str] = None, show_empty: bool = False
         Returns the specific metadata of a need inside docutils nodes.
         Usage::
 
-            <<meta('status', prefix='**status**', show_empty=True)>>
+            <<meta('status', prefix='\\*\\*status\\*\\*: ', show_empty=True)>>
+
+        .. note::
+
+           You must escape all rst_content in your function strings! E.g. to get `**` one must use `\\\\*\\\\*`.
 
         :param name: name of the need item
         :param prefix: string as rst-code, will be added infront of the value output

tests/doc_test/doc_layout/conf.py

@@ -30,6 +30,13 @@
             "side": ['<<image("_images/{{author}}.png", align="center")>>'],
         },
     },
+    "optional_author": {
+        "grid": "simple",
+        "layout": {
+            "head": ['**<<meta("title")>>**'],
+            "meta": ['**status**: <<meta("status")>>', r'<<meta("author", prefix="\*\*author\*\*: ")>>'],
+        },
+    },
     "footer_grid": {
         "grid": "simple_footer",
         "layout": {

tests/doc_test/doc_layout/index.rst

@@ -13,5 +13,9 @@ TEST DOCUMENT
 .. spec:: title_example_layout
    :layout: example
 
+.. spec:: title_layout_optional_author
+   :layout: optional_author
+   :author: some author
+
 .. spec:: title_layout_footer_grid
    :layout: footer_grid

tests/test_layouts.py

@@ -23,8 +23,11 @@ def test_doc_build_html(test_app):
     assert "title_example_layout" in html
 
     needs = extract_needs_from_html(html)
-    assert len(needs) == 5
+    assert len(needs) == 6
 
+    assert (
+        '<span class="needs_label"><strong>author</strong>: </span><span class="needs_data">some author</span>' in html
+    )
     assert '<tr class="footer row-even"><td class="footer_left" colspan="2">' in html
 
     # check simple_footer grid layout