Merge branch 'master' into fix/1095-warn-links

useblocks · Feb 12, 2024 · adee6b6 · adee6b6
2 parents a46d824 + f6b090a
commit adee6b6
Show file tree

Hide file tree

Showing 18 changed files with 175 additions and 217 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -18,9 +18,7 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import os
-from typing import Any, Dict, List
-
-from sphinx.application import Sphinx
+from typing import Any, Dict
 
 from sphinx_needs import __version__
 
@@ -82,43 +80,11 @@
    {% endif %}
 """
 
-EXTRA_CONTENT_TEMPLATE_COLLAPSE = """
-.. _{{id}}:
-
-{% if hide == false -%}
-.. role:: needs_tag
-.. role:: needs_status
-.. role:: needs_type
-.. role:: needs_id
-.. role:: needs_title
-
-.. rst-class:: need
-.. rst-class:: need_{{type_name}}
-
-.. dropdown::
-   :class: need
-
-            :needs_type:`{{type_name}}`: {% if title %}:needs_title:`{{title}}`{% endif %} :needs_id:`{{id}}`
-
-{% if status and  status|upper != "NONE" and not hide_status %}        | status: :needs_status:`{{status}}`{% endif %}
-{% if tags and not hide_tags %}        | tags: :needs_tag:`{{tags|join("` :needs_tag:`")}}`{% endif %}
-{% if my_extra_option != "" %}        | my_extra_option: {{ my_extra_option }}{% endif %}
-{% if another_option != "" %}        | another_option: {{ another_option }}{% endif %}
-        | links incoming: :need_incoming:`{{id}}`
-        | links outgoing: :need_outgoing:`{{id}}`
-
-    {{content|indent(4) }}
-
-{% endif -%}
-"""
-
 DEFAULT_DIAGRAM_TEMPLATE = (
     "<size:12>{{type_name}}</size>\\n**{{title|wordwrap(15, wrapstring='**\\\\n**')}}**\\n<size:10>{{id}}</size>"
 )
 
 # You can uncomment some of the following lines to override the default configuration for Sphinx-Needs.
-
-# needs_template = TITLE_TEMPLATE
 # needs_diagram_template = DEFAULT_DIAGRAM_TEMPLATE
 
 # Absolute path to the needs_report_template_file based on the conf.py directory
@@ -251,7 +217,6 @@
 needs_table_style = "datatables"
 needs_table_columns = "ID;TITLE;STATUS;OUTGOING"
 
-needs_template_collapse = EXTRA_CONTENT_TEMPLATE_COLLAPSE
 needs_extra_options = [
     "my_extra_option",
     "another_option",
@@ -543,25 +508,6 @@ def custom_defined_func():
 html_context = {}
 
 
-def rstjinja(app: Sphinx, _docname: str, source: List[str]) -> None:
-    """
-    Render our pages as a jinja template for fancy templating goodness.
-    """
-    # Make sure we're outputting HTML
-    if app.builder.format != "html" and app.builder.name != "linkcheck":
-        return
-    src = source[0]
-    from jinja2 import Template
-
-    template = Template(src, autoescape=True)
-    rendered = template.render(**app.config.html_context)
-    source[0] = rendered
-
-
-def setup(app: Sphinx) -> None:
-    app.connect("source-read", rstjinja)
-
-
 # LINKCHECK config
 # https://www.sphinx-doc.org/en/master/usage/configuration.html?highlight=linkcheck#options-for-the-linkcheck-builder
 linkcheck_ignore = [

diff --git a/docs/configuration.rst b/docs/configuration.rst
@@ -667,8 +667,6 @@ If you do not set ``needs_report_template``, the default template used is:
 
 .. code-block:: jinja
 
-   {% raw -%}
-
    {# Output for needs_types #}
    {% if types|length != 0 %}
    .. dropdown:: Need Types
@@ -745,7 +743,7 @@ If you do not set ``needs_report_template``, the default template used is:
    {% endif %}
    {# Output for needs metrics #}
 
-   {% endraw %}
+   
 
 The plugin provides the following variables which you can use in your custom Jinja template:
 
@@ -776,13 +774,12 @@ By default the following template is used:
 
 .. code-block:: jinja
 
-    {% raw -%}
     {%- if is_need -%}
     <size:12>{{type_name}}</size>\\n**{{title|wordwrap(15, wrapstring='**\\\\n**')}}**\\n<size:10>{{id}}</size>
     {%- else -%}
     <size:12>{{type_name}} (part)</size>\\n**{{content|wordwrap(15, wrapstring='**\\\\n**')}}**\\n<size:10>{{id_parent}}.**{{id}}**</size>
     {%- endif -%}
-    {% endraw %}
+    
 
 
 .. _needs_id_required:
@@ -1556,7 +1553,7 @@ Default: ``False``.
     needs_service_all_data = True
 
 
-{% raw %}
+
 
 .. _needs_external_needs:
 
@@ -1632,7 +1629,7 @@ keys:
             The related CSS class definition must be done by the user, e.g. by :ref:`own_css`.
             (*optional*) (*default*: ``external_link``)
 
-{% endraw %}
+
 
 .. _needs_needextend_strict:
 
@@ -1724,7 +1721,7 @@ All named capture group values get injected, so that parts of the option-value c
 link name and url.
 
 **Example**:
-{% raw %}
+
 
 .. code-block:: python
 
@@ -1746,7 +1743,7 @@ link name and url.
             'options': ['github']
         }
     }
-{% endraw %}
+
 
 |ex|
 
@@ -1961,7 +1958,7 @@ constraints_results is a dictionary similar in structure to needs_constraints ab
             "critical": {
                 "check_0": "'critical' in tags",
                 "severity": "CRITICAL",
-                "error_message": "need {% raw %}{{id}}{% endraw %} does not fulfill CRITICAL constraint, because tags are {% raw %}{{tags}}{% endraw %}"
+                "error_message": "need {{id}} does not fulfill CRITICAL constraint, because tags are {{tags}}"
             }
         
         }
@@ -2143,8 +2140,6 @@ You can use the data passed via needs_render_context as shown below:
 
 .. code-block:: jinja
 
-    {% raw -%}
-
     .. req:: Need with jinja_content enabled
        :id: JINJA1D8913
        :jinja_content: true
@@ -2159,9 +2154,7 @@ You can use the data passed via needs_render_context as shown below:
             + author[1]
        {% endfor %}
 
-    {% endraw %}
-
-{% raw -%}
+    
 
 .. req:: Need with jinja_content enabled
    :id: JINJA1D8913
@@ -2174,7 +2167,7 @@ You can use the data passed via needs_render_context as shown below:
    * {{ author[0] }} --> ID-{{ author[1] }}
    {% endfor %}
 
-{% endraw %}
+
 
 
 .. _needs_debug_measurement:
@@ -2211,8 +2204,6 @@ If nothing is set, the following default template is used:
 
 .. code-block:: jinja
 
-   {% raw -%}
-
    .. _{{id}}:
 
    {% if hide == false -%}
@@ -2242,7 +2233,7 @@ If nothing is set, the following default template is used:
 
    {% endif -%}
 
-   {% endraw %}
+   
 
 Available jinja variables are:
 
@@ -2260,7 +2251,7 @@ Available jinja variables are:
 
 .. warning::
 
-   You must add a reference like `.. _{{ '{{id}}' }}:` to the template. Otherwise linking will not work!
+   You must add a reference like `.. _{{id}}:` to the template. Otherwise linking will not work!
 
 .. _needs_template_collapse:
 
@@ -2274,8 +2265,6 @@ Default value:
 
 .. code-block:: jinja
 
-    {% raw -%}
-
     .. _{{id}}:
 
     {% if hide == false -%}
@@ -2304,7 +2293,7 @@ Default value:
        {{content|indent(4) }}
 
    {% endif -%}
-   {% endraw %}
+   
 
 For more details please see :ref:`needs_template`.
 

diff --git a/docs/directives/need.rst b/docs/directives/need.rst
@@ -197,7 +197,7 @@ and stores its PlantUML code under given key from :ref:`needuml` directive under
 
 This diagram data can then be used in other :ref:`needuml` calls to combine and reuse PlantUML elements.
 
-{% raw %}
+
 
 |ex|
 
@@ -251,7 +251,7 @@ Reuse of :need:`SP_INT` inside a :ref:`needuml`:
 
    system => int_a
 
-{% endraw %}
+
 
 This simple mechanism is really powerful to design reusable and configurable SW architecture diagrams.
 For more examples and details, please read :ref:`needuml`.
@@ -553,7 +553,6 @@ Default: False
 
 .. code-block:: jinja
 
-    {% raw -%}
     .. req:: First Req Need
        :id: JINJAID123
        :jinja_content: false
@@ -584,12 +583,10 @@ Default: False
        Need with ``:jinja_content:`` equal to ``true``.
        This requirement has status: **{{ status }}**.
 
-    {% endraw %}
+    
 
 |out|
 
-{% raw -%}
-
 .. req:: First Req Need
    :id: JINJAID123
    :jinja_content: false
@@ -620,7 +617,7 @@ Default: False
    Need with ``:jinja_content:`` equal to ``true``.
    This requirement has status: **{{ status }}**.
 
-{% endraw %}
+
 
 .. _title_from_content:
 

diff --git a/docs/directives/needarch.rst b/docs/directives/needarch.rst
@@ -1,4 +1,4 @@
-{% raw %}
+
 
 .. _needarch:
 
@@ -256,4 +256,4 @@ does detect different parameter sets and does import `uml()` calls with differen
       {{uml('COMP_T_002')}}
       {% endif %}
 
-{% endraw %}
+
diff --git a/docs/directives/needreport.rst b/docs/directives/needreport.rst
@@ -21,6 +21,16 @@ The :ref:`needs_report_template` value is a path to the
 `jinja2 <https://jinja.palletsprojects.com/en/2.11.x/templates/>`_ template file.
 You can use the template file to customise the content generated  by ``needreport``.
 
+.. note::
+
+   The default needs report template is set to use ``dropdown`` directives for containing each configuration type, which requires the ``dropdown`` directive to be available in your Sphinx environment. If you do not have the ``dropdown`` directive available, you can use the following configuration to set the default needs report template to use ``admonition`` directives instead:
+
+   .. code-block:: python
+
+      needs_render_context = {
+         "report_directive": "admonition",
+      }
+
 |ex|
 
 .. code-block:: rst

diff --git a/docs/directives/needuml.rst b/docs/directives/needuml.rst
@@ -1,4 +1,4 @@
-{% raw %}
+
 
 .. _needuml:
 
@@ -741,4 +741,4 @@ NeedUml Examples
 
       class_x o-- class_y
 
-{% endraw %}
+
diff --git a/docs/layout_styles.rst b/docs/layout_styles.rst
@@ -287,13 +287,13 @@ The head-line for the default Sphinx-Needs layout ``clean`` looks like this::
 You are free to surround a layout function with a rst role. Like ``**<<meta("title")>>**`` to get a bold printed title.
 
 Sometimes an argument for a layout function shall be based on a given need option. In this cases the option name
-can be surrounded by ``{%raw%}{{ .. }}{%endraw%}``.
+can be surrounded by ``{{ .. }}``.
 As example, there may be an ``author`` option in a bug-need and you want to show a picture of the author in the grid
 ``simple_side_right_partial``.
 
 The line for the ``side`` area could look like::
 
-   '<<image("_images/{%raw%}{{author}}{%endraw%}.png", align="center")>>'
+   '<<image("_images/{{author}}.png", align="center")>>'
 
 .. spec:: My test spec
    :author: daniel
@@ -326,7 +326,7 @@ Here is the complete used code::
                'head': ['**<<meta("title")>>** for *<<meta("author")>>*'],
                'meta': ['**status**: <<meta("status")>>',
                         '**author**: <<meta("author")>>'],
-               'side': ['<<image("_images/{%raw%}{{author}}{%endraw%}.png", align="center")>>']
+               'side': ['<<image("_images/{{author}}.png", align="center")>>']
            }
        }
    }

diff --git a/docs/roles.rst b/docs/roles.rst
@@ -202,21 +202,9 @@ They are also getting the part_id as link description.
 
 |out|
 
-{% if READTHEDOCS %}
-..
-
-.. image:: _static/need_part_as_flow.png
-   :align: center
-
-{% else %}
-
 .. needflow::
    :filter: id in ["my_car_1","impl_my_car_1"]
 
-{% endif %}
-
-
-
 **Presentation in needtable**
 
 Please see :ref:`needtable_show_parts` of :ref:`needtable` configuration documentation.