From 14fffc5b61834185bea6cdde70b05b92093d8e70 Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Mon, 3 Jun 2024 09:04:57 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9A=20Use=20new=20need-example=20direc?= =?UTF-8?q?tive=20for=20all=20examples=20(#1190)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit removes the duplication of examples (as literal and rendered), by adding a `need-example` directive that handles both from the same source content. This removes issues with inconsistencies, and also allows for consistent/centralised formatting of the examples. --- docs/_static/_css/sphinx_immaterial.css | 7 + docs/builders.rst | 3 - docs/conf.py | 47 ++- docs/configuration.rst | 133 ++------- docs/directives/need.rst | 366 ++--------------------- docs/directives/needarch.rst | 122 +------- docs/directives/needbar.rst | 369 ++---------------------- docs/directives/needextend.rst | 200 ++++--------- docs/directives/needextract.rst | 24 +- docs/directives/needflow.rst | 189 +----------- docs/directives/needgantt.rst | 84 +----- docs/directives/needimport.rst | 8 +- docs/directives/needlist.rst | 44 +-- docs/directives/needpie.rst | 143 +-------- docs/directives/needreport.rst | 45 +-- docs/directives/needsequence.rst | 21 +- docs/directives/needservice.rst | 25 +- docs/directives/needtable.rst | 215 ++++---------- docs/directives/needuml.rst | 308 ++------------------ docs/roles.rst | 176 ++--------- 20 files changed, 342 insertions(+), 2187 deletions(-) diff --git a/docs/_static/_css/sphinx_immaterial.css b/docs/_static/_css/sphinx_immaterial.css index 67ac4e5d9..8f90720f0 100644 --- a/docs/_static/_css/sphinx_immaterial.css +++ b/docs/_static/_css/sphinx_immaterial.css @@ -180,3 +180,10 @@ body { width: 100%; padding-right: 0.6em !important; /* note, this line can be removed in sphinx-design v0.6.1 */ } + +.needs-example { + border: .05rem solid rgb(72,138,87); + padding-left: .5rem; + padding-right: .5rem; + padding-bottom: .5rem; +} diff --git a/docs/builders.rst b/docs/builders.rst index e0b0d57c7..0833fd2e8 100644 --- a/docs/builders.rst +++ b/docs/builders.rst @@ -50,9 +50,6 @@ or :ref:`needflow` gets exported, if the option :ref:`export_id` is used in the This allows to export specified filter results only. - -|ex|: - .. code-block:: rst .. needtable:: diff --git a/docs/conf.py b/docs/conf.py index 4bf7499d7..f22efca71 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -52,10 +52,6 @@ rst_epilog = """ -.. |ex| replace:: **Example** - -.. |out| replace:: **Result** - .. |br| raw:: html
@@ -612,3 +608,46 @@ def custom_defined_func(): # Absolute path to the needs_report_template_file based on the conf.py directory # needs_report_template = "/needs_templates/report_template.need" # Use custom report template + +# -- custom extensions --------------------------------------- + +from docutils import nodes # noqa: E402 +from sphinx.application import Sphinx # noqa: E402 +from sphinx.directives import SphinxDirective # noqa: E402 + + +class NeedExampleDirective(SphinxDirective): + """Directive to add example content to the documentation. + + It adds a container with a title, a code block, and a parsed content block. + """ + + optional_arguments = 1 + final_argument_whitespace = True + has_content = True + + def run(self): + count = self.env.temp_data.setdefault("needs-example-count", 0) + count += 1 + self.env.temp_data["needs-example-count"] = count + root = nodes.container(classes=["needs-example"]) + self.set_source_info(root) + title = f"Example {count}" + title_nodes, _ = ( + self.state.inline_text(f"{title}: {self.arguments[0]}", self.lineno) + if self.arguments + else ([nodes.Text(title)], []) + ) + root += nodes.rubric("", "", *title_nodes) + code = nodes.literal_block( + "", "\n".join(self.content), language="rst", classes=["needs-example-raw"] + ) + root += code + parsed = nodes.container(classes=["needs-example-raw"]) + root += parsed + self.state.nested_parse(self.content, self.content_offset, parsed) + return [root] + + +def setup(app: Sphinx): + app.add_directive("need-example", NeedExampleDirective) diff --git a/docs/configuration.rst b/docs/configuration.rst index 5c808c9bb..c71086068 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -343,28 +343,15 @@ Configuration example: The above example configuration allows the following usage: -|ex| - -.. code-block:: rst +.. need-example:: .. req:: My requirement - :id: EXTRA_REQ_001 + :id: EXTRA_REQ_001 .. test:: Test of requirements - :id: EXTRA_TEST_001 - :checks: EXTRA_REQ_001, DEAD_LINK_NOT_ALLOWED - :triggers: DEAD_LINK - - -|out| - -.. req:: My requirement - :id: EXTRA_REQ_001 - -.. test:: Test of requirements - :id: EXTRA_TEST_001 - :checks: EXTRA_REQ_001, DEAD_LINK_NOT_ALLOWED - :triggers: DEAD_LINK + :id: EXTRA_TEST_001 + :checks: EXTRA_REQ_001, DEAD_LINK_NOT_ALLOWED + :triggers: DEAD_LINK .. attention:: The used option name can not be reused in the configuration of :ref:`needs_global_options`. @@ -541,8 +528,6 @@ Fields can be added or existing fields can even be manipulated. If set to False, the filter results contains the original need fields and any manipulations of need fields are lost. -|ex| - .. code-block:: python needs_allow_unsafe_filters = True @@ -611,21 +596,13 @@ These configs can then be selected when using :ref:`needflow`. This configurations can then be used like this: -|ex| +.. need-example:: -.. code-block:: rst - - .. needflow:: - :tags: flow_example - :types: spec - :config: my_config - -|out| + .. needflow:: + :tags: flow_example + :types: spec + :config: my_config -.. needflow:: - :tags: flow_example - :types: spec - :config: my_config See :ref:`needflow config option ` for more details and already available configurations. @@ -809,11 +786,9 @@ needs_id_from_title Generates needs ID from title. By default, this setting is set to **False**. When no need ID is given by the user, and `needs_id_from_title` is set to **True**, then a need ID -will be calculated based on the current need directive prefix, title, and a hased value from title. +will be calculated based on the current need directive prefix, title, and a hashed value from title. -|ex| - -.. code-block:: rst +.. need-example:: .. req:: Group big short @@ -853,9 +828,10 @@ A title can be auto-generated for a requirement by either setting :ref:`needs_title_from_content` to **True** or providing the flag `:title_from_content:` as follows: -|ex| +The resulting requirement would have the title derived from the first +sentence of the requirement. -.. code-block:: rst +.. need-example:: .. req:: :title_from_content: @@ -863,17 +839,6 @@ A title can be auto-generated for a requirement by either setting This will be my title. Anything after the first sentence will not be part of the title. -The resulting requirement would have the title derived from the first -sentence of the requirement. - -|out| - -.. req:: - :title_from_content: - - This will be my title. Anything after the first sentence will not be - part of the title. - .. _needs_title_from_content: @@ -896,22 +861,12 @@ setting (which is not limited by default). If a title is specified for an individual requirement, then that title will be used over the generated title. -|ex| - -.. code-block:: rst +.. need-example:: .. req:: - The tool must have error logging. All critical errors must be - written to the console. - - -This will render the first sentence as the title - -.. req:: - - The tool must have error logging. All critical errors must be - written to the console. + The tool must have error logging. + All critical errors must be written to the console. .. _needs_max_title_length: @@ -1710,9 +1665,7 @@ link name and url. } -|ex| - -.. code-block:: rst +.. need-example:: .. spec:: Use needs_string_links :id: EXAMPLE_STRING_LINKS @@ -1721,15 +1674,6 @@ link name and url. Replaces the string from ``:config:`` and ``:github:`` with a link to the related website. -|out| - -.. spec:: Use needs_string_links - :id: EXAMPLE_STRING_LINKS - :config: needs_string_links - :github: 404,652 - - Replaces the string from ``:config:`` and ``:github:`` with a link to the related website. - .. note:: You must define the options specified under :ref:`needs_string_links` inside :ref:`needs_extra_options` as well. @@ -2024,9 +1968,7 @@ needs_variants ``needs_variants`` configuration option must be a dictionary which has pre-defined variants assigned to "filter strings". The filter string defines which variant a need belongs in the current situations. -|ex| - -In ``conf.py``: +For example, in ``conf.py``: .. code-block:: python @@ -2049,9 +1991,7 @@ needs_variant_options ``needs_variant_options`` must be a list which consists of the options to apply variants handling. You can specify the names of the options you want to check for variants. -|ex| - -In ``conf.py``: +for example, in ``conf.py``: .. code-block:: python @@ -2082,28 +2022,24 @@ Configuration example: def custom_defined_func(): return "my_tag" - def sum_example(number_1, number_2): - return number_1 + number_2 - needs_render_context = { "custom_data_1": "Project_X", "custom_data_2": custom_defined_func(), "custom_data_3": True, "custom_data_4": [("Daniel", 811982), ("Marco", 234232)], - "sum_example": sum_example } The``needs_render_context`` configuration option must be a dictionary. The dictionary consists of key-value pairs where the key is a string used as reference to the value. -The value can be any data type (string, integer, list, dict, etc.) or a custom defined function, which return -value is used or the function itself can be used (see ``sum_example``). +The value can be any data type (string, integer, list, dict, etc.) + +.. warning:: The value can also be a custom defined function, + however, this will deactivate the caching and incremental build feature of Sphinx. The data passed via needs_render_context will be available as variable(s) when rendering Jinja templates or strings. You can use the data passed via needs_render_context as shown below: -|ex| - -.. code-block:: jinja +.. need-example:: .. req:: Need with jinja_content enabled :id: JINJA1D8913 @@ -2111,29 +2047,12 @@ You can use the data passed via needs_render_context as shown below: Need with alias {{ custom_data_1 }} and ``jinja_content`` option set to {{ custom_data_3 }}. - 4 + 5 = {{ sum_example(4,5) }} - {{ custom_data_2 }} {% for author in custom_data_4 %} * author[0] + author[1] {% endfor %} - - -.. req:: Need with jinja_content enabled - :id: JINJA1D8913 - :jinja_content: true - - Need with alias {{ custom_data_1 }} and ``jinja_content`` option set to {{ custom_data_3 }}. - - {{ custom_data_2 }} - {% for author in custom_data_4 %} - * {{ author[0] }} --> ID-{{ author[1] }} - {% endfor %} - - - .. _needs_debug_measurement: diff --git a/docs/directives/need.rst b/docs/directives/need.rst index 959032cc4..ff35ac82a 100644 --- a/docs/directives/need.rst +++ b/docs/directives/need.rst @@ -6,9 +6,7 @@ need / req (or any other defined need type) Creates a **need** object with a specified type. You can define the type using the correct directive, like ``.. req::`` or ``.. test::``. -|ex| - -.. code-block:: rst +.. need-example:: .. req:: User needs to login :id: ID123 @@ -18,16 +16,6 @@ You can define the type using the correct directive, like ``.. req::`` or ``.. t Our users needs to get logged in via our login forms on **/login.php**. -.. rubric:: **Output** - -.. req:: User needs to login - :id: ID123 - :status: open - :tags: user;login - :collapse: false - - Our users needs to get logged in via our login forms on **/login.php**. - The code example above creates a new requirement, with a title, content, given id, a status and several tags. All the options for the requirement directive ( ``req`` ) are optional, @@ -88,9 +76,7 @@ In this example, you set the :ref:`needs_variants` configuration that comprises "filter strings". You can then use the keys in your ``needs_variants`` as references when defining variants for a *need option*. -|ex| - -In ``conf.py``: +For example, in your ``conf.py``: .. code-block:: python @@ -116,9 +102,7 @@ Use Case 2 In this example, you can use the filter string directly in the *need option's* variant definition. -|ex| - -In your ``.rst`` file: +For example, in your ``.rst`` file: .. code-block:: rst @@ -136,8 +120,6 @@ In this example, you can use defined tags (via the `-t `_) in the *need option's* variant definition. -|ex| - First of all, define your Sphinx-Tags using either the ``-t`` command-line ``sphinx-build`` option: .. code-block:: bash @@ -165,9 +147,7 @@ If a variant definition is true, then we set the *need option* to the value of t Below is an implementation of variants for need options: -|ex| - -.. code-block:: rst +.. need-example:: .. req:: Variant options :id: VA_004 @@ -177,16 +157,6 @@ Below is an implementation of variants for need options: Variants for need options in action -|out| - -.. req:: Variant options - :id: VA_004 - :status: ['variants' in tags and not collapse]:enabled, disabled - :tags: variants;support - :collapse: - - Variants for need options in action - .. _need_diagram: Diagram support @@ -197,11 +167,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. - - -|ex| - -.. code-block:: rst +.. need-example:: .. spec:: Interfaces :id: SP_INT @@ -226,32 +192,6 @@ This diagram data can then be used in other :ref:`needuml` calls to combine and system => int_a -|out| - -.. spec:: Interfaces - :id: SP_INT - :status: open - - This are the provided interfaces: - - .. needuml:: - - circle "Int A" as int_a - circle "Int B" as int_b - circle "Int C" as int_c - -Reuse of :need:`SP_INT` inside a :ref:`needuml`: - -.. needuml:: - - allowmixing - - {{uml("SP_INT")}} - node "My System" as system - - system => int_a - - This simple mechanism is really powerful to design reusable and configurable SW architecture diagrams. For more examples and details, please read :ref:`needuml`. @@ -261,23 +201,13 @@ Filter for diagrams The option ``arch`` can be easily used for filtering. For instance to show all need objects, which are representing some kind of a diagram. - -|ex| - -.. code-block:: rst +.. need-example:: .. needtable:: :filter: bool(arch) :style: table :columns: id, type, title -|out| - -.. needtable:: - :filter: bool(arch) - :style: table - :columns: id, type, title - Options for Need Type --------------------- @@ -315,9 +245,7 @@ All you must specify is the ID for the need. You can easily set links to multiple needs by using **;** as a separator. -|ex| - -.. code-block:: rst +.. need-example:: .. req:: Link example Target :id: REQ_LINK_1 @@ -329,19 +257,6 @@ You can easily set links to multiple needs by using **;** as a separator. This sets a link to id ``REQ_LINK_1``. -|out| - -.. req:: Link example Target - :id: REQ_LINK_1 - - This is the target for a link. Itself has no link set. - -.. req:: Link example Source - :links: REQ_LINK_1 - - This sets a link to id ``REQ_LINK_1``. - - .. _need_extra_links: extra links @@ -349,8 +264,6 @@ extra links By using :ref:`needs_extra_links `, you can use the configured link-types to set additional **need** options. -|ex| - .. code-block:: python # conf.py @@ -369,7 +282,7 @@ By using :ref:`needs_extra_links `, you can use the configure } ] -.. code-block:: rst +.. need-example:: .. req:: test me :id: test_req @@ -382,21 +295,6 @@ By using :ref:`needs_extra_links `, you can use the configure Perform some tests -|out| - -.. req:: test me - :id: test_req - :collapse: false - - A requirement, which needs to be tested - -.. test:: test a requirement - :id: test_001 - :tests: test_req - :collapse: false - - Perform some tests - .. _need_delete: delete @@ -419,9 +317,7 @@ Default: False If you delete a need using the :delete: option, the need will not be part of any filter result. -|ex| - -.. code-block:: rst +.. need-example:: .. req:: First Requirement Need :id: DELID123 @@ -442,27 +338,6 @@ Default: False Need with ``:delete:`` option not set. -|out| - -.. req:: First Requirement Need - :id: DELID123 - :status: open - :delete: true - - Need with ``:delete:`` equal to ``true``. - -.. req:: Second Requirement Need - :id: DELID123 - :delete: false - - Need with ``:delete:`` equal to ``false``. - - .. spec:: Nested Need without delete option - :id: DELID124 - :tags: nested-del-need - - Need with ``:delete:`` option not set. - .. _need_hide: @@ -487,9 +362,7 @@ Allowed values: Default: False -|ex| - -.. code-block:: rst +.. need-example:: .. req:: Collapse is set to True :tags: collapse; example @@ -503,20 +376,6 @@ Default: False Title, tags, links and everything else is shown directly. -|out| - -.. req:: Collapse is set to True - :tags: collapse; example - :collapse: - - Only title and content are shown - -.. req:: Collapse is set to False - :tags: collapse; example - :collapse: False - - Title, tags, links and everything else is shown directly. - .. _jinja_content: jinja_content @@ -549,9 +408,7 @@ Default: False } -|ex| - -.. code-block:: jinja +.. need-example:: .. req:: First Req Need :id: JINJAID123 @@ -583,42 +440,6 @@ Default: False Need with ``:jinja_content:`` equal to ``true``. This requirement has status: **{{ status }}**. - - -|out| - -.. req:: First Req Need - :id: JINJAID123 - :jinja_content: false - - Need with ``:jinja_content:`` equal to ``false``. - - .. spec:: Nested Spec Need - :id: JINJAID124 - :status: open - :tags: user;login - :links: JINJAID126 - :jinja_content: - - Nested need with ``:jinja_content:`` option set to ``true``. - This requirement has tags: **{{ tags | join(', ') }}**. - - It links to: - {% for link in links %} - - {{ link }} - {% endfor %} - - -.. spec:: First Spec Need - :id: JINJAID126 - :status: open - :jinja_content: - - Need with ``:jinja_content:`` equal to ``true``. - This requirement has status: **{{ status }}**. - - - .. _title_from_content: title_from_content @@ -641,26 +462,13 @@ elided title if needed. By default there is no limit to the title length. If a title is provided and the flag is present, then the provided title will be used and a warning will be issued. -|ex| - -.. code-block:: rst +.. need-example:: .. req:: :title_from_content: - The first sentence will be the title. Anything after the first - sentence will not be part of the title. - -|out| - -The resulting requirement would have the title derived from the first -sentence of the requirement. - -.. req:: - :title_from_content: - - The first sentence will be the title. Anything after the first - sentence will not be part of the title. + The first sentence will be the title. + Anything after the first sentence will not be part of the title. .. _need_layout: @@ -671,9 +479,7 @@ layout ``layout`` can be used to set a specific grid and content mapping. -|ex| - -.. code-block:: rst +.. need-example:: .. req:: My layout requirement 1 :id: LAYOUT_1 @@ -682,18 +488,7 @@ layout Some **content** of LAYOUT_1 -|out| - -.. req:: My layout requirement 1 - :id: LAYOUT_1 - :tags: layout_example - :layout: clean - - Some **content** of LAYOUT_1 - -|ex| - -.. code-block:: rst +.. need-example:: .. req:: My layout requirement 2 :id: LAYOUT_2 @@ -702,18 +497,7 @@ layout Some **content** of LAYOUT_2 -|out| - -.. req:: My layout requirement 2 - :id: LAYOUT_2 - :tags: layout_example - :layout: complete - - Some **content** of LAYOUT_2 - -|ex| - -.. code-block:: rst +.. need-example:: .. req:: My layout requirement 3 :id: LAYOUT_3 @@ -722,15 +506,6 @@ layout Some **content** of LAYOUT_3 -|out| - -.. req:: My layout requirement 3 - :id: LAYOUT_3 - :tags: layout_example - :layout: focus - - Some **content** of LAYOUT_3 - Please take a look into :ref:`layouts` for more information. @@ -842,15 +617,11 @@ default ``needs_templates/``, in the **conf.py** file. You can have several templates, but can set only one for a need. -|ex| - -*Template:* spec_template.need +.. dropdown:: Template ``spec_template.need`` -.. literalinclude:: /needs_templates/spec_template.need + .. literalinclude:: /needs_templates/spec_template.need -*Need* - -.. code-block:: rst +.. need-example:: .. spec:: My specification :status: open @@ -861,17 +632,6 @@ You can have several templates, but can set only one for a need. This is my **specification** content. -|out| - -.. spec:: My specification - :status: open - :links: FEATURE_1, FEATURE_2 - :id: TEMPL_SPEC - :tags: example, template - :template: spec_template - - This is my **specification** content. - You can find a list of need-value names in the documentation for :ref:`filter_string` or by using the ``debug`` :ref:`layout `. @@ -886,10 +646,11 @@ In Sphinx, options support multi-line content, which you can interpret like othe But there is one important constraint: Don’t use empty lines, as we use them in defining the content end. Instead, you can use ``__`` (two underscores) to define the content end and can use ``|`` to force line breaks. -|ex| +.. dropdown:: *Template* ``content.need`` -*Need* -:: + .. literalinclude:: /needs_templates/content.need + +.. need-example:: .. req:: A really strange example :id: multiline_1234 @@ -922,44 +683,7 @@ Instead, you can use ``__`` (two underscores) to define the content end and can .. image:: /_images/needs_logo.png :width: 30% :template: content - -*Template* - -.. literalinclude:: /needs_templates/content.need - -|out| - -.. req:: A really strange example - :id: multiline_1234 - :status: - | First line - | Second line - | Followed by an empty line - __ - A list example: - __ - * take *this* - * and **this** - __ - __ - __ - 3 new lines, but 1 is shown only - __ - Included directives - __ - .. req:: test req - :id: abc_432 - __ - This works! - __ - An image: wow - __ - .. image:: /_images/needs_logo.png - :width: 20% - __ - .. image:: /_images/needs_logo.png - :width: 30% - :template: content + :collapse: true .. _need_pre_template: @@ -971,15 +695,11 @@ pre_template Adds specific content from a template *before* a **need**. For example, you can use it to set a section name before each **need**. -|ex| - -*Template:* spec_pre_template.need - -.. literalinclude:: /needs_templates/spec_pre_template.need +.. dropdown:: *Template:* ``spec_pre_template.need`` -*Need* + .. literalinclude:: /needs_templates/spec_pre_template.need -.. code-block:: rst +.. need-example:: .. spec:: My specification :id: TEMPL_PRE_SPEC @@ -988,15 +708,6 @@ For example, you can use it to set a section name before each **need**. This is my **specification** content. -|out| - -.. spec:: My specification - :id: TEMPL_PRE_SPEC - :tags: example, template - :pre_template: spec_pre_template - - This is my **specification** content. - .. _need_post_template: post_template @@ -1007,15 +718,11 @@ post_template Adds specific content from a template *after* a **need**. You can use it to show some need-specific analytics, like dependency diagrams or table of linked needs. -|ex| +.. dropdown:: *Template:* ``spec_post_template.need`` -*Template:* spec_post_template.need + .. literalinclude:: /needs_templates/spec_post_template.need -.. literalinclude:: /needs_templates/spec_post_template.need - -*Need* - -.. code-block:: rst +.. need-example:: .. spec:: My specification :id: TEMPL_POST_SPEC @@ -1025,17 +732,6 @@ You can use it to show some need-specific analytics, like dependency diagrams or This is my **specification** content. -|out| - -.. spec:: My specification - :id: TEMPL_POST_SPEC - :tags: example, template - :links: FEATURE_1, FEATURE_2 - :post_template: spec_post_template - - This is my **specification** content. - - .. _need_duration: duration diff --git a/docs/directives/needarch.rst b/docs/directives/needarch.rst index 383bd1e6b..aebe10da6 100644 --- a/docs/directives/needarch.rst +++ b/docs/directives/needarch.rst @@ -8,9 +8,7 @@ needarch ``needarch`` behaves exactly like :ref:`needuml`, but only works inside a need. It provides also additional exclusive jinja functions :ref:`needarch_jinja_need` and :ref:`needarch_jinja_import`. -|ex| - -.. code-block:: rst +.. need-example:: .. req:: Requirement arch :id: req_arch_001 @@ -22,18 +20,6 @@ jinja functions :ref:`needarch_jinja_need` and :ref:`needarch_jinja_import`. Alice -> Bob: Hi Bob Bob --> Alice: hi Alice -|out| - -.. req:: Requirement arch - :id: req_arch_001 - - .. needarch:: - :scale: 50 - :align: center - - Alice -> Bob: Hi Bob - Bob --> Alice: hi Alice - Jinja context ------------- @@ -49,9 +35,7 @@ need() The `need()` function provides you the need information the :ref:`needarch` is embedded in. -|ex| - -.. code-block:: rst +.. need-example:: .. req:: Req Arch four :id: req_arch_004 @@ -70,25 +54,6 @@ The `need()` function provides you the need information the :ref:`needarch` is e {% endfor %} } -|out| - -.. req:: Req Arch four - :id: req_arch_004 - :status: draft - :blocks: req_arch_001 - - content. - - .. needarch:: - :scale: 50 - :align: center - - class "{{need().title}}" { - {{need().status}} - {% for e in need().blocks %}{{e}} - {% endfor %} - } - .. _needarch_jinja_import: @@ -99,9 +64,7 @@ This function takes undefined amounts of current need links option names as argu Then it executes :ref:`needuml_jinja_uml` automatically for all links/need_ids defined from the given arguments. -|ex| - -.. code-block:: rst +.. need-example:: .. req:: Req Arch second :id: req_arch_002 @@ -126,37 +89,6 @@ Then it executes :ref:`needuml_jinja_uml` automatically for all links/need_ids d {{import("checks", "tests")}} -|out| - -.. req:: Req Arch second - :id: req_arch_002 - - arch req content. - -.. req:: Req Arch third - :id: req_arch_003 - - some req stuff. - -.. spec:: Spec Arch first - :id: spec_arch_001 - - some spec content. - -.. test:: Test Arch - :id: test_arch_001 - :checks: req_arch_002 - :triggers: req_arch_003, spec_arch_001 - - Test need arch jinja import function. - - .. needarch:: - :scale: 50 - :align: center - - {{import("checks", "triggers")}} - - .. _needarch_ex_loop: NeedArch Loop Example @@ -170,9 +102,7 @@ you have, if so please create an issue and mention this chapter. The algorithm does detect different parameter sets and does import `uml()` calls with different :ref:`parameter ` to the same need. -|ex| - -.. code-block:: rst +.. need-example:: .. comp:: COMP_T_001 :id: COMP_T_001 @@ -213,47 +143,3 @@ does detect different parameter sets and does import `uml()` calls with differen {% else %} {{uml('COMP_T_002')}} {% endif %} - -|out| - -.. comp:: COMP_T_001 - :id: COMP_T_001 - - .. needarch:: - - {{flow(need().id)}} - {% if variant == "A" %} - {{uml('COMP_T_003', variant="A")}} - usecase {{need().id}}_usecase - {% else %} - {{uml('COMP_T_003')}} - {{uml('COMP_T_003', variant="A")}} - {% endif %} - -.. comp:: COMP_T_002 - :id: COMP_T_002 - - .. needarch:: - - {{flow(need().id)}} - {% if variant == "A" %} - {{uml('COMP_T_001', variant="A")}} - usecase {{need().id}}_usecase - {% else %} - {{uml('COMP_T_001')}} - {% endif %} - -.. comp:: COMP_T_003 - :id: COMP_T_003 - - .. needarch:: - - {{flow(need().id)}} - {% if variant == "A" %} - {{uml('COMP_T_002', variant="A")}} - usecase {{need().id}}_usecase - {% else %} - {{uml('COMP_T_002')}} - {% endif %} - - diff --git a/docs/directives/needbar.rst b/docs/directives/needbar.rst index 8810e17b3..e824d2390 100644 --- a/docs/directives/needbar.rst +++ b/docs/directives/needbar.rst @@ -7,9 +7,7 @@ needbar ``needbar`` adds a bar-chart to your documentation: -|ex| - -.. code-block:: rst +.. need-example:: .. needbar:: @@ -18,15 +16,6 @@ needbar 15,10,20 20,15,10 -|out| - -.. needbar:: - - 5,20,15 - 10,15,10 - 15,10,20 - 20,15,10 - Each content value gets interpreted either as static float/int value or as a :ref:`filter_string`. The amount of found needs by the filter string is then used as value. @@ -40,32 +29,7 @@ Options Example with all options used: -.. needbar:: Full bar chart - :legend: - :colors: #ffcc88, #ffcc00, #444444 - :text_color: crimson - :style: dark_background - :x_axis_title: x_axis_title - :xlabels_rotation: 90 - :xlabels: a, b, c - :y_axis_title: y_axis_title - :ylabels: FROM_DATA - :ylabels_rotation: 45 - :separator: ; - :stacked: - :show_top_sum: - :show_sum: - :sum_rotation: 90 - :transpose: - :horizontal: - - Z; 5;20;15 - Y;10;15;10 - X;15;10;20 - W;20;15;10 - - -.. code-block:: rst +.. need-example:: .. needbar:: Full bar chart :legend: @@ -91,15 +55,12 @@ Example with all options used: X;15;10;20 W;20;15;10 - title ~~~~~ You can specify the headline of the bar chart using the ``title`` argument. -|ex| - -.. code-block:: rst +.. need-example:: .. needbar:: Title example @@ -108,21 +69,9 @@ You can specify the headline of the bar chart using the ``title`` argument. 15,10,20 20,15,10 -|out| - -.. needbar:: Title example - - 5,20,15 - 10,15,10 - 15,10,20 - 20,15,10 - - It is possible to create bar charts without title. -|ex| - -.. code-block:: rst +.. need-example:: .. needbar:: @@ -131,16 +80,6 @@ It is possible to create bar charts without title. 15,10,20 20,15,10 -|out| - -.. needbar:: - - 5,20,15 - 10,15,10 - 15,10,20 - 20,15,10 - - content ~~~~~~~ @@ -152,9 +91,7 @@ We get the bar chart's data (values) from the amount of **need** objects found b Below is a more realistic example with data fetched from filters, together with hardcoded data: -|ex| - -.. code-block:: rst +.. need-example:: .. needbar:: A more real bar chart :legend: @@ -166,19 +103,6 @@ Below is a more realistic example with data fetched from filters, together with Test, type=='test' and status=='open', type=='test' and status=='in progress', type=='test' and status=='closed', type=='test' and status=='done', type=='test' and status=='implemented', 7 Specification, type=='spec' and status=='open', type=='spec' and status=='in progress', type=='spec' and status=='closed', type=='spec' and status=='done', type=='spec' and status=='implemented', 9 -|out| - -.. needbar:: A more real bar chart - :legend: - :xlabels: FROM_DATA - :ylabels: FROM_DATA - - , open , in progress , closed , done , implemented , number - Requirement, type=='req' and status=='open', type=='req' and status=='in progress', type=='req' and status=='closed', type=='req' and status=='done', type=='req' and status=='implemented', 5 - Test, type=='test' and status=='open', type=='test' and status=='in progress', type=='test' and status=='closed', type=='test' and status=='done', type=='test' and status=='implemented', 7 - Specification, type=='spec' and status=='open', type=='spec' and status=='in progress', type=='spec' and status=='closed', type=='spec' and status=='done', type=='spec' and status=='implemented', 9 - - legend ~~~~~~ @@ -186,9 +110,7 @@ You can place a legend on the barchart by setting the ``:legend:`` flag. The ``:legend:`` flag does not support any values. -|ex| - -.. code-block:: rst +.. need-example:: .. needbar:: Legend example :legend: @@ -198,16 +120,6 @@ The ``:legend:`` flag does not support any values. 15,10,20 20,15,10 -|out| - -.. needbar:: Legend example - :legend: - - 5,20,15 - 10,15,10 - 15,10,20 - 20,15,10 - axis title ~~~~~~~~~~ @@ -217,9 +129,7 @@ You can enable axis titles on the barchart by setting the ``:x_axis_title:`` or If you use `horizontal`_ or `transpose`_, the meaning of ``:x_axis_title:`` and ``:y_axis_title:`` must be understandable. So you have to change the description accordingly. -|ex| - -.. code-block:: rst +.. need-example:: .. needbar:: Axis title example :x_axis_title: types @@ -230,18 +140,6 @@ You can enable axis titles on the barchart by setting the ``:x_axis_title:`` or 15,10,20 20,15,10 -|out| - -.. needbar:: Axis title example - :x_axis_title: types - :y_axis_title: numbers - - 5,20,15 - 10,15,10 - 15,10,20 - 20,15,10 - - labels ~~~~~~ @@ -257,9 +155,7 @@ Also, you can set the ``:xlabels:`` and/or ``:ylabels:`` value to ``FROM_DATA`` But if you use `horizontal`_ or `transpose`_, the meaning of ``:x_axis_title:`` and ``:y_axis_title:`` will change automatically. -|ex| - -.. code-block:: rst +.. need-example:: .. needbar:: Labels example 1 :legend: @@ -271,9 +167,6 @@ Also, you can set the ``:xlabels:`` and/or ``:ylabels:`` value to ``FROM_DATA`` 15,10,20 20,15,10 - -.. code-block:: rst - .. needbar:: Labels example 2 :legend: :xlabels: FROM_DATA @@ -286,30 +179,6 @@ Also, you can set the ``:xlabels:`` and/or ``:ylabels:`` value to ``FROM_DATA`` W,20,15,10 -|out| - -.. needbar:: Labels example 1 - :legend: - :xlabels: a, b, c - :ylabels: Z, Y, X, W - - 5,20,15 - 10,15,10 - 15,10,20 - 20,15,10 - -.. needbar:: Labels example 2 - :legend: - :xlabels: FROM_DATA - :ylabels: FROM_DATA - - , a, b, c - Z, 5,20,15 - Y,10,15,10 - X,15,10,20 - W,20,15,10 - - stacked ~~~~~~~ @@ -317,9 +186,7 @@ You can render the barchart in a stacked design by setting ``:stacked:`` flag. The ``:stacked:`` flag does not support any values. -|ex| - -.. code-block:: rst +.. need-example:: .. needbar:: stacked example :stacked: @@ -329,16 +196,6 @@ The ``:stacked:`` flag does not support any values. 15,10,20 20,15,10 -|out| - -.. needbar:: stacked example - :stacked: - - 5,20,15 - 10,15,10 - 15,10,20 - 20,15,10 - show_sum ~~~~~~~~ @@ -346,9 +203,7 @@ You can render the barchart with detailed information of the height of each bar The ``:show_sum:`` flag does not support any values and it's useful with the ``stacked`` option enabled. -|ex| - -.. code-block:: rst +.. need-example:: .. needbar:: show_sum example 1 :show_sum: @@ -358,8 +213,6 @@ The ``:show_sum:`` flag does not support any values and it's useful with the ``s 15,10,20 20,15,10 -.. code-block:: rst - .. needbar:: show_sum example 2 :stacked: :show_sum: @@ -369,25 +222,6 @@ The ``:show_sum:`` flag does not support any values and it's useful with the ``s 15,10,20 20,15,10 -|out| - -.. needbar:: show_sum example 1 - :show_sum: - - 5,20,15 - 10,15,10 - 15,10,20 - 20,15,10 - -.. needbar:: show_sum example 2 - :stacked: - :show_sum: - - 5,20,15 - 10,15,10 - 15,10,20 - 20,15,10 - show_top_sum ~~~~~~~~~~~~ @@ -396,9 +230,7 @@ You can render the barchart with detailed information of the height of each bar The ``:show_sum:`` flag does not support any values and it's useful with the ``stacked`` option enabled. -|ex| - -.. code-block:: rst +.. need-example:: .. needbar:: show_top_sum example 1 :show_top_sum: @@ -408,8 +240,6 @@ The ``:show_sum:`` flag does not support any values and it's useful with the ``s 15,10,20 20,15,10 -.. code-block:: rst - .. needbar:: show_top_sum example 2 :stacked: :show_sum: @@ -420,27 +250,6 @@ The ``:show_sum:`` flag does not support any values and it's useful with the ``s 15,10,20 20,15,10 -|out| - -.. needbar:: show_top_sum example 1 - :show_top_sum: - - 5,20,15 - 10,15,10 - 15,10,20 - 20,15,10 - -.. needbar:: show_top_sum example 2 - :stacked: - :show_sum: - :show_top_sum: - - 5,20,15 - 10,15,10 - 15,10,20 - 20,15,10 - - horizontal ~~~~~~~~~~ @@ -452,9 +261,7 @@ The ``:horizontal:`` flag does not support any values and it's useful with the ` The meaning of `labels`_ will change automatically with the usage of ``:horizontal:``. We will use the ``:x_axis_title:`` as labels for the y-axis and use the ``:y_axis_title:`` as the values in the `legend`_. -|ex| - -.. code-block:: rst +.. need-example:: .. needbar:: horizontal example 1 :horizontal: @@ -464,8 +271,6 @@ The ``:horizontal:`` flag does not support any values and it's useful with the ` 15,10,20 20,15,10 -.. code-block:: rst - .. needbar:: horizontal example 2 :stacked: :legend: @@ -480,31 +285,6 @@ The ``:horizontal:`` flag does not support any values and it's useful with the ` X,15,10,20 W,20,15,10 -|out| - -.. needbar:: horizontal example 1 - :horizontal: - - 5,20,15 - 10,15,10 - 15,10,20 - 20,15,10 - -.. needbar:: horizontal example 2 - :stacked: - :legend: - :show_sum: - :horizontal: - :xlabels: FROM_DATA - :ylabels: FROM_DATA - - , a, b, c - Z, 5,20,15 - Y,10,15,10 - X,15,10,20 - W,20,15,10 - - transpose ~~~~~~~~~ @@ -517,9 +297,7 @@ The ``:transpose:`` flag does not support any values and it's useful with big co * Using the ``:transpose:`` flag, transposes the ``:x_axis_title:`` and ``:y_axis_title:`` fetched from the content data or specified with `labels`_ but does not transpose the extra `axis title`_. * Remember that with the ``:transpose:`` flag, the length and height of the content data changes, not to think about the width of matching elements, like `colors`_. Please review the impact of ``:transpose:`` before using it. -|ex| - -.. code-block:: rst +.. need-example:: .. needbar:: transpose example 1 :transpose: @@ -529,8 +307,6 @@ The ``:transpose:`` flag does not support any values and it's useful with big co 15,10,20 20,15,10 -.. code-block:: rst - .. needbar:: transpose example 2 :legend: :stacked: @@ -545,30 +321,6 @@ The ``:transpose:`` flag does not support any values and it's useful with big co X,15,10,20 W,20,15,10 -|out| - -.. needbar:: transpose example 1 - :transpose: - - 5,20,15 - 10,15,10 - 15,10,20 - 20,15,10 - -.. needbar:: transpose example 2 - :legend: - :stacked: - :show_sum: - :transpose: - :xlabels: FROM_DATA - :ylabels: FROM_DATA - - , a, b, c - Z, 5,20,15 - Y,10,15,10 - X,15,10,20 - W,20,15,10 - rotation ~~~~~~~~ @@ -578,9 +330,7 @@ rotation | Use ``:sum_rotation:`` to set rotation of labels for bars on the diagram. -|ex| - -.. code-block:: rst +.. need-example:: .. needbar:: rotation example :legend: @@ -597,24 +347,6 @@ rotation 15,10,20 20,15,10 -|out| - -.. needbar:: rotation example - :legend: - :xlabels: a, b, c - :xlabels_rotation: 90 - :ylabels: Z, Y, X, W - :ylabels_rotation: 40 - :show_top_sum: - :show_sum: - :sum_rotation: 90 - - 5,20,15 - 10,15,10 - 15,10,20 - 20,15,10 - - separator ~~~~~~~~~ @@ -623,9 +355,7 @@ This ensures the use of ``,`` (the default separator) in a filter rule. Other op The ``:separator:`` is a string that supports any symbols. -|ex| - -.. code-block:: rst +.. need-example:: .. needbar:: separator example :separator: - @@ -635,17 +365,6 @@ The ``:separator:`` is a string that supports any symbols. 15-10-20 20-15-10 -|out| - -.. needbar:: separator example - :separator: - - - 5-20-15 - 10-15-10 - 15-10-20 - 20-15-10 - - colors ~~~~~~ @@ -661,9 +380,7 @@ But besides names, ``:colors:`` options also supports hex-values like ``#ffcc00` When you use `horizontal`_ or `transpose`_, the bar's length must be equal to ``:xlabels:`` or ``:ylabels:``. If the length does not fit, it will fill the bar with the colors again and you will get a warning. -|ex| - -.. code-block:: rst +.. need-example:: .. needbar:: colors example :legend: @@ -677,33 +394,16 @@ But besides names, ``:colors:`` options also supports hex-values like ``#ffcc00` X,15,10,20 W,20,15,10 -|out| - -.. needbar:: colors example - :legend: - :colors: lightcoral, gold, #555555, #888888 - :xlabels: FROM_DATA - :ylabels: FROM_DATA - - , a, b, c - Z, 5,20,15 - Y,10,15,10 - X,15,10,20 - W,20,15,10 - - text_color ~~~~~~~~~~ ``:text_color:`` defines the color for text inside the bar chart and the labels. -|ex| - -.. code-block:: rst +.. need-example:: .. needbar:: text_color example :legend: - text_color: green + :text_color: green :xlabels: FROM_DATA :ylabels: FROM_DATA @@ -713,21 +413,6 @@ text_color X,15,10,20 W,20,15,10 -|out| - -.. needbar:: text_color example - :legend: - :text_color: green - :xlabels: FROM_DATA - :ylabels: FROM_DATA - - , a, b, c - Z, 5,20,15 - Y,10,15,10 - X,15,10,20 - W,20,15,10 - - style ~~~~~ @@ -743,9 +428,7 @@ Useful styles are for example: * dark_background * grayscale -|ex| - -.. code-block:: rst +.. need-example:: .. needbar:: style example :legend: @@ -758,17 +441,3 @@ Useful styles are for example: Y,10,15,10 X,15,10,20 W,20,15,10 - -|out| - -.. needbar:: style example - :legend: - :style: Solarize_Light2 - :xlabels: FROM_DATA - :ylabels: FROM_DATA - - , a, b, c - Z, 5,20,15 - Y,10,15,10 - X,15,10,20 - W,20,15,10 diff --git a/docs/directives/needextend.rst b/docs/directives/needextend.rst index bc606e299..771934ccc 100644 --- a/docs/directives/needextend.rst +++ b/docs/directives/needextend.rst @@ -5,9 +5,7 @@ needextend .. versionadded:: 0.7.0 ``needextend`` allows to modify existing needs. It doesn’t provide any output, as the modifications -get presented at the original location of the changing need. - -|ex| +get presented at the original location of the changing need, for example: .. code-block:: rst @@ -27,52 +25,27 @@ The argument of ``needextend`` must be a :ref:`filter_string` which defines the ``needextend`` can modify all string-based and list-based options. Also, you can add links or delete tags. -|ex| - -.. code-block:: rst - - .. req:: needextend Example 1 - :id: extend_test_001 - :status: open - :author: Foo - :tags: tag_1, tag_2 - - This requirement got modified. - - | Status was **open**, now it is **[[copy('status')]]**. - | Also author got changed from **Foo** to **[[copy('author')]]**. - | And a tag was added. - | Finally all links got removed. - - .. needextend:: id == "extend_test_001" - :status: closed - :+author: and me - :+tags: new_tag - -|out| - -.. req:: needextend Example 1 - :id: extend_test_001 - :status: open - :author: Foo - :tags: tag_1, tag_2 - :links: FEATURE_1 +.. need-example:: - This requirement got modified. + .. req:: needextend Example 1 + :id: extend_test_001 + :status: open + :author: Foo + :tags: tag_1, tag_2 + :links: FEATURE_1 - | Status was **open**, now it is **[[copy('status')]]**. - | Also author got changed from **Foo** to **[[copy('author')]]**. - | And a tag was added. - | Finally all links got removed. + This requirement got modified. -.. needextend:: id == "extend_test_001" - :status: closed - :+author: and me - :+tags: new_tag - :+links: FEATURE_2, FEATURE_3 + | Status was **open**, now it is **[[copy('status')]]**. + | Also author got changed from **Foo** to **[[copy('author')]]**. + | And a tag was added. + | Finally all links got removed. -.. This is a useless comment, but needed to supress a bug in docutils 0.18.1 , which can not handle -.. the above needextend if followed by a new sections. + .. needextend:: id == "extend_test_001" + :status: closed + :+author: and me + :+tags: new_tag + :+links: FEATURE_2, FEATURE_3 Options ------- @@ -106,9 +79,7 @@ Single need modification ------------------------ If only one single need shall get modified, the argument of ``needextend`` can just be the need-id. -|ex| - -.. code-block:: rst +.. need-example:: .. req:: needextend Example 2 :id: extend_test_002 @@ -117,15 +88,6 @@ If only one single need shall get modified, the argument of ``needextend`` can j .. needextend:: extend_test_002 :status: New status -|out| - -.. req:: needextend Example 2 - :id: extend_test_002 - :status: open - -.. needextend:: extend_test_002 - :status: New status - .. attention:: The given argument must fully match the regular expression defined in @@ -136,8 +98,6 @@ Setting default option values ----------------------------- You can use ``needextend``'s filter string to set default option values for a group of needs. -|ex| - The following example would set the status of all needs in the document ``docs/directives/needextend.rst``, which do not have the status set explicitly, to ``open``. @@ -155,90 +115,48 @@ Options containing links get handled in two steps: 1. Options for the need are set as above. 2. The referenced need get updated as well and incoming links may get deleted, added or replaced. -|ex| - -.. code-block:: rst - - .. req:: needextend Example 3 - :id: extend_test_003 - - Had no outgoing links. - Got an outgoing link ``extend_test_004``. - - .. req:: needextend Example 4 - :id: extend_test_004 - - Had no links. - Got an incoming links ``extend_test_003`` and ``extend_test_006``. - - .. req:: needextend Example 5 - :id: extend_test_005 - :links: extend_test_003, extend_test_004 - - Had the two links: ``extend_test_003`` and ``extend_test_004``. - Both got deleted. - - .. req:: needextend Example 6 - :id: extend_test_006 - :links: extend_test_003 - - Had the link ``extend_test_003``, got another one ``extend_test_004``. - - .. -- MANIPULATIONS -- - - .. needextend:: extend_test_003 - :links: extend_test_004 +.. need-example:: - .. needextend:: extend_test_005 - :-links: + .. req:: needextend Example 3 + :id: extend_test_003 - .. needextend:: extend_test_006 - :+links: extend_test_004 + Had no outgoing links. + Got an outgoing link ``extend_test_004``. - .. needextend:: extend_test_006 - :+links: extend_test_004 + .. req:: needextend Example 4 + :id: extend_test_004 - Same as above, so it should not do anything. - But it raises the modified-counter by one. + Had no links. + Got an incoming links ``extend_test_003`` and ``extend_test_006``. -|out| + .. req:: needextend Example 5 + :id: extend_test_005 + :links: extend_test_003, extend_test_004 -.. req:: needextend Example 3 - :id: extend_test_003 + Had the two links: ``extend_test_003`` and ``extend_test_004``. + Both got deleted. - Had no outgoing links. - Got an outgoing link ``extend_test_004``. + .. req:: needextend Example 6 + :id: extend_test_006 + :links: extend_test_003 -.. req:: needextend Example 4 - :id: extend_test_004 + Had the link ``extend_test_003``, got another one ``extend_test_004``. - Had no links. - Got an incoming links ``extend_test_003`` and ``extend_test_006``. + .. needextend:: extend_test_003 + :links: extend_test_004 -.. req:: needextend Example 5 - :id: extend_test_005 - :links: extend_test_003, extend_test_004 + .. needextend:: extend_test_005 + :-links: - Had the two links: ``extend_test_003`` and ``extend_test_004``. - Both got deleted. + .. needextend:: extend_test_006 + :+links: extend_test_004 -.. req:: needextend Example 6 - :id: extend_test_006 - :links: extend_test_003 + .. Same as above, so it should not do anything. + + .. But it raises the modified-counter by one. - Had the link ``extend_test_003``, got another one ``extend_test_004``. - -.. needextend:: extend_test_003 - :links: extend_test_004 - -.. needextend:: extend_test_005 - :-links: - -.. needextend:: extend_test_006 - :+links: extend_test_004 - -.. needextend:: extend_test_006 - :+links: extend_test_004 + .. needextend:: extend_test_006 + :+links: extend_test_004 Monitoring modifications ------------------------ @@ -255,21 +173,11 @@ To see these values, use ``:layout: debug`` on the need or by :ref:`own_layouts` Also filtering for these values is supported: -|ex| - -.. code-block:: rst - - We have :need_count:`is_modified` modified needs. - - .. needtable:: - :filter: "needextend" in title - :columns: id, title, is_modified, modifications - -|out| +.. need-example:: -We have :need_count:`is_modified` modified needs. + We have :need_count:`is_modified` modified needs. -.. needtable:: - :filter: "needextend" in title - :columns: id, title, is_modified, modifications - :style: table + .. needtable:: + :filter: "needextend" in title + :columns: id, title, is_modified, modifications + :style: table diff --git a/docs/directives/needextract.rst b/docs/directives/needextract.rst index 9c7fca530..67872de08 100644 --- a/docs/directives/needextract.rst +++ b/docs/directives/needextract.rst @@ -10,8 +10,6 @@ needextract It supports custom creation of extracts from existing needs. For instance, a supplier could get a copy of requirements but would not see all the internal meta-data. -|ex| - .. code-block:: rst .. needextract:: @@ -26,8 +24,6 @@ For instance, a supplier could get a copy of requirements but would not see all ``needextract`` supports also arguments as filter string. It works like the option `filter`, but also supports need ID as filter argument. -|ex| - .. code-block:: rst .. needextract:: FEATURE_3 @@ -49,20 +45,12 @@ The original need provides the style information, if not overwritten by :ref:`ne See :ref:`layouts` for a list of available layouts. -|ex| - -.. code-block:: rst +.. need-example:: .. needextract:: :filter: id in ['FEATURE_3', 'FEATURE_4'] :layout: focus_r -|out| - -.. needextract:: - :filter: id in ['FEATURE_3', 'FEATURE_4'] - :layout: focus_r - .. _needextract_style: style @@ -73,16 +61,8 @@ The original need provides the layout information , if not overwritten by :ref:` See :ref:`styles` for a list of available styles. -|ex| - -.. code-block:: rst +.. need-example:: .. needextract:: :filter: id in ['FEATURE_3', 'FEATURE_4'] :style: blue_border - -|out| - -.. needextract:: - :filter: id in ['FEATURE_3', 'FEATURE_4'] - :style: blue_border diff --git a/docs/directives/needflow.rst b/docs/directives/needflow.rst index 24e5de3fa..32984dcfa 100644 --- a/docs/directives/needflow.rst +++ b/docs/directives/needflow.rst @@ -9,9 +9,7 @@ needflow If you provide an argument, we use it as caption for the generated image. -|ex| - -.. code-block:: rst +.. need-example:: .. needflow:: My first needflow :filter: is_need @@ -19,14 +17,6 @@ If you provide an argument, we use it as caption for the generated image. :link_types: tests, blocks :show_link_names: -|out| - -.. needflow:: My first needflow - :filter: is_need - :tags: flow_example - :link_types: tests, blocks - :show_link_names: - Dependencies ------------ @@ -66,9 +56,7 @@ If ``:root_depth:`` is set, only needs with a distance of ``root_depth`` to the Other need filters are applied on this initial selection of connected needs. -|ex| - -.. code-block:: rst +.. need-example:: .. needflow:: :root_id: spec_flow_002 @@ -89,27 +77,6 @@ Other need filters are applied on this initial selection of connected needs. :link_types: tests, blocks :show_link_names: -|out| - -.. needflow:: - :root_id: spec_flow_002 - :root_direction: incoming - :link_types: tests, blocks - :show_link_names: - -.. needflow:: - :root_id: spec_flow_002 - :root_direction: outgoing - :link_types: tests, blocks - :show_link_names: - -.. needflow:: - :root_id: spec_flow_002 - :root_direction: outgoing - :root_depth: 1 - :link_types: tests, blocks - :show_link_names: - .. _needflow_show_filters: show_filters @@ -117,21 +84,12 @@ show_filters Adds information of used filters below generated flowchart. -|ex| - -.. code-block:: rst +.. need-example:: .. needflow:: :tags: main_example :show_filters: -|out| - -.. needflow:: - :tags: main_example - :show_filters: - - .. _needflow_show_legend: show_legend @@ -140,20 +98,12 @@ show_legend Adds a legend below generated flowchart. The legends contains all defined need-types and their configured color for flowcharts. -|ex| - -.. code-block:: rst +.. need-example:: .. needflow:: :tags: main_example :show_legend: -|out| - -.. needflow:: - :tags: main_example - :show_legend: - .. _needflow_show_link_names: show_link_names @@ -164,23 +114,14 @@ show_link_names Adds the link type name beside connections. You can configure it globally by setting :ref:`needs_flow_show_links` in **conf.py**. +Setup data can be found in test case document `tests/doc_test/doc_extra_links`. -|ex| - -.. code-block:: rst +.. need-example:: .. needflow:: :tags: main_example :show_link_names: -Setup data can be found in test case document `tests/doc_test/doc_extra_links` - -|out| - -.. needflow:: - :tags: main_example - :show_link_names: - .. _needflow_link_types: link_types @@ -210,9 +151,7 @@ You can set this option globally via the configuration option :ref:`needs_flow_l See also :ref:`needs_extra_links` for more details about specific link types. -|ex| - -.. code-block:: rst +.. need-example:: .. req:: A requirement :id: req_flow_001 @@ -248,42 +187,6 @@ See also :ref:`needs_extra_links` for more details about specific link types. :link_types: tests, blocks :show_link_names: -|out| - -.. req:: A requirement - :id: req_flow_001 - :tags: flow_example - -.. spec:: A specification - :id: spec_flow_001 - :blocks: req_flow_001 - :tags: flow_example - - :need_part:`(subspec_1)A testable part of the specification` - - :need_part:`(subspec_2)Another testable part of the specification` - - .. spec:: A child specification - :id: spec_flow_003 - :blocks: req_flow_001 - :tags: flow_example - -.. spec:: Another specification - :id: spec_flow_002 - :links: req_flow_001 - :blocks: spec_flow_001 - :tags: flow_example - -.. test:: A test case - :id: test_flow_001 - :tests: spec_flow_002, spec_flow_001.subspec_1, spec_flow_001.subspec_2 - :tags: flow_example - -.. needflow:: - :tags: flow_example - :link_types: tests, blocks - :show_link_names: - .. _needflow_config: config @@ -294,9 +197,7 @@ config You can specify a configuration using the ``:config:`` option but you should set the :ref:`needs_flow_configs` configuration parameter in **conf.py**. -|ex| - -.. code-block:: rst +.. need-example:: .. needflow:: :filter: is_need @@ -306,21 +207,9 @@ set the :ref:`needs_flow_configs` configuration parameter in **conf.py**. :show_link_names: :config: monochrome -|out| - -.. needflow:: - :filter: is_need - :tags: flow_example - :types: spec - :link_types: tests, blocks - :show_link_names: - :config: monochrome - You can apply multiple configurations together by separating them via ``,`` symbol. -|ex| - -.. code-block:: rst +.. need-example:: .. needflow:: :filter: is_need @@ -330,16 +219,6 @@ You can apply multiple configurations together by separating them via ``,`` symb :show_link_names: :config: monochrome,lefttoright,handwritten -|out| - -.. needflow:: - :filter: is_need - :tags: flow_example - :types: spec - :link_types: tests, blocks - :show_link_names: - :config: monochrome,lefttoright,handwritten - **Sphinx-Needs** provides some necessary configurations already. They are: .. list-table:: @@ -378,9 +257,7 @@ You can set a scale factor for the final flow chart using the ``scale`` option. We also support the numbers between ``1`` and ``300``. -|ex| - -.. code-block:: rst +.. need-example:: .. needflow:: :filter: is_need @@ -388,14 +265,6 @@ We also support the numbers between ``1`` and ``300``. :link_types: tests, blocks :scale: 50 -|out| - -.. needflow:: - :filter: is_need - :tags: flow_example - :link_types: tests, blocks - :scale: 50 - .. _needflow_highlight: highlight @@ -406,22 +275,13 @@ highlight The ``:highlight:`` option takes a single :ref:`filter_string` as a value and sets the border for each need of the needflow to **red** if the need also passes the filter string. -|ex| - -.. code-block:: rst +.. need-example:: .. needflow:: :tags: flow_example :link_types: tests, blocks :highlight: id in ['spec_flow_002', 'subspec_2'] or type == 'req' -|out| - -.. needflow:: - :tags: flow_example - :link_types: tests, blocks - :highlight: id in ['spec_flow_002', 'subspec_2'] or type == 'req' - .. _needflow_align: align @@ -430,22 +290,13 @@ align You can set the alignment for the PlantUML image using the ``align`` option. Allowed values are: ``left``, ``center``, ``right`` -|ex| - -.. code-block:: rst +.. need-example:: .. needflow:: - :filter: is_need + :filter: is_need and type == 'spec' :tags: flow_example :align: center -|out| - -.. needflow:: - :filter: is_need and type == 'spec' - :tags: flow_example - :align: center - .. _needflow_debug: debug @@ -457,9 +308,7 @@ If you set the ``:debug:``, we add a debug-output of the generated PlantUML code Helpful to identify reasons why a PlantUML build may have thrown errors. -|ex| - -.. code-block:: rst +.. need-example:: .. needflow:: :filter: is_need @@ -468,16 +317,6 @@ Helpful to identify reasons why a PlantUML build may have thrown errors. :config: lefttoright, handwritten :debug: -|out| - -.. needflow:: - :filter: is_need - :tags: flow_example - :link_types: tests, blocks - :config: lefttoright, handwritten - :debug: - - common filters ~~~~~~~~~~~~~~ diff --git a/docs/directives/needgantt.rst b/docs/directives/needgantt.rst index 38a817a04..248e7ed9e 100644 --- a/docs/directives/needgantt.rst +++ b/docs/directives/needgantt.rst @@ -7,20 +7,12 @@ needgantt ``needgantt`` adds a gantt-chart to your documentation. -|ex| - -.. code-block:: rst +.. need-example:: .. needgantt:: Bug handling gantt :tags: gantt_example :milestone_filter: type == 'milestone' -|out| - -.. needgantt:: Bug handling gantt - :tags: gantt_example - :milestone_filter: type == 'milestone' - .. dropdown:: Show used needs for above example .. action:: Find & Report bug @@ -121,20 +113,12 @@ List of link names used to define task relationship, ``starts_with``. Default: None -|ex| - -.. code-block:: rst +.. need-example:: .. needgantt:: Starts_with example :tags: gantt_ex_starts_with :starts_with_links: starts_with -|out| - -.. needgantt:: Starts_with example - :tags: gantt_ex_starts_with - :starts_with_links: starts_with - .. dropdown:: Show used needs for above example .. action:: Create example @@ -163,20 +147,12 @@ List of link names used to define task relationship, ``starts_after``. Default: links -|ex| - -.. code-block:: rst +.. need-example:: .. needgantt:: Starts_after example :tags: gantt_ex_starts_after :starts_after_links: starts_after -|out| - -.. needgantt:: Starts_with example - :tags: gantt_ex_starts_after - :starts_after_links: starts_after - .. dropdown:: Show the needs used in the above example .. action:: Create example @@ -199,20 +175,12 @@ List of link names used to define task relationship, ``ends_with``. Default: None -|ex| - -.. code-block:: rst +.. need-example:: .. needgantt:: Ends_with example :tags: gantt_ex_ends_with :ends_with_links: ends_with -|out| - -.. needgantt:: Ends_with example - :tags: gantt_ex_ends_with - :ends_with_links: ends_with - .. dropdown:: Show the needs used in the above example .. action:: Create example @@ -236,23 +204,13 @@ We calculate all tasks and milestones dates based on the ``:start_date:`` option Date format must be ``YYYY-MM-DD``. Example: 2020-03-25 -|ex| - -.. code-block:: rst +.. need-example:: .. needgantt:: Bug handling gantt :tags: gantt_example :milestone_filter: type == 'milestone' :start_date: 2020-03-25 -|out| - -.. needgantt:: Bug handling gantt - :tags: gantt_example - :milestone_filter: type == 'milestone' - :start_date: 2020-03-25 - - .. _needgantt_timeline: timeline @@ -266,9 +224,7 @@ Default: ``daily`` Works only, if you set :ref:`needgantt_start_date` option. -|ex| - -.. code-block:: rst +.. need-example:: .. needgantt:: Bug handling gantt :tags: gantt_example @@ -276,14 +232,6 @@ Works only, if you set :ref:`needgantt_start_date` option. :start_date: 2020-03-25 :timeline: weekly -|out| - -.. needgantt:: Bug handling gantt - :tags: gantt_example - :milestone_filter: type == 'milestone' - :start_date: 2020-03-25 - :timeline: weekly - .. _needgantt_no_color: no_color @@ -309,20 +257,12 @@ You can set the duration option globally by using :ref:`needs_duration_option` i Default: :ref:`need_duration` -|ex| - -.. code-block:: rst +.. need-example:: .. needgantt:: Duration example :tags: gantt_ex_duration :duration_option: hours -|out| - -.. needgantt:: Duration example - :tags: gantt_ex_duration - :duration_option: hours - .. dropdown:: Show the needs used in the above example .. action:: Create example @@ -353,20 +293,12 @@ You can set the completion option globally by using :ref:`needs_completion_optio Default: :ref:`need_completion` -|ex| - -.. code-block:: rst +.. need-example:: .. needgantt:: Completion example :tags: gantt_ex_completion :completion_option: amount -|out| - -.. needgantt:: Completion example - :tags: gantt_ex_completion - :completion_option: amount - .. dropdown:: Show the needs used in the above example .. action:: Create example diff --git a/docs/directives/needimport.rst b/docs/directives/needimport.rst index 387ca1de2..0a34f9b65 100644 --- a/docs/directives/needimport.rst +++ b/docs/directives/needimport.rst @@ -6,9 +6,7 @@ needimport ``needimport`` allows the import of needs from a JSON file. -You can generate a valid file using the builder :ref:`needs_builder`. - -|ex| +You can generate a valid file using the builder :ref:`needs_builder`, for example: .. code-block:: rst @@ -26,9 +24,7 @@ You can generate a valid file using the builder :ref:`needs_builder`. The directive needs an absolute or relative path as argument. If the path is relative, we derive an absolute path based on the location of the document being compiled. -The directive also supports URL as argument to download ``needs.json`` from remote. - -|ex| +The directive also supports URL as argument to download ``needs.json`` from remote, for example: .. code-block:: rst diff --git a/docs/directives/needlist.rst b/docs/directives/needlist.rst index 08e45ebda..5f627fce5 100644 --- a/docs/directives/needlist.rst +++ b/docs/directives/needlist.rst @@ -7,18 +7,11 @@ needlist **needlist** creates a list of elements based on the result of given filters. -|ex| - -.. code-block:: rst +.. need-example:: .. needlist:: :tags: main_example -|out| - -.. needlist:: - :tags: main_example - Options ------- @@ -36,17 +29,7 @@ Flag for adding status information to the needs list results filtered. If a filtered need has no status information, we write no status output for the need. -.. dropdown:: Show example - - |ex| - - .. code-block:: rst - - .. needlist:: - :show_status: - :status: done; implemented - - |out| +.. need-example:: .. needlist:: :show_status: @@ -60,23 +43,13 @@ Flag for adding tag information to the needs list results filtered. If a filtered need has no tag information, we write no tag output for the need. -.. dropdown:: Show example - |ex| - - .. code-block:: rst - - .. needlist:: - :show_tags: - :status: done; implemented - - |out| +.. need-example:: .. needlist:: :show_tags: :status: done; implemented - .. _needlist_show_filters: show_filters @@ -84,17 +57,8 @@ show_filters If set, we add the used filter below the needlist results: -.. dropdown:: Show example - - |ex| - - .. code-block:: rst - - .. needlist:: - :show_filters: - :status: done; implemented - |out| +.. need-example:: .. needlist:: :show_filters: diff --git a/docs/directives/needpie.rst b/docs/directives/needpie.rst index 95f36924c..1bfa2b294 100644 --- a/docs/directives/needpie.rst +++ b/docs/directives/needpie.rst @@ -7,9 +7,7 @@ needpie ``needpie`` adds a pie-chart to your documentation. -|ex| - -.. code-block:: rst +.. need-example:: .. needpie:: My pie chart @@ -17,14 +15,6 @@ needpie type == 'spec' 10 -|out| - -.. needpie:: My pie chart - - type == 'req' - type == 'spec' - 10 - If you provide an argument for the ``needpie``, we use it as the title. Each content line gets interpreted either as static float/int value or as a :ref:`filter_string`. @@ -42,7 +32,7 @@ Options **Example with all options used:** -.. code-block:: rst +.. need-example:: .. needpie:: Requirement status :labels: Open, In progress, Closed @@ -57,21 +47,6 @@ Options type == 'req' and status == 'in progress' type == 'req' and status == 'closed' -|out| - -.. needpie:: Requirement status - :labels: Open, In progress, Closed - :legend: - :shadow: - :explode: 0, 0.3, 0 - :colors: #ffcc00, #444444, limegreen - :text_color: crimson - :style: dark_background - - type == 'req' and status == 'open' - type == 'req' and status == 'in progress' - type == 'req' and status == 'closed' - labels ~~~~~~ @@ -81,9 +56,7 @@ Use ``:labels:`` to set labels for each value. ``:labels:`` must get a comma separated string and the amount of labels must match the amount of values/lines from content. -|ex| - -.. code-block:: rst +.. need-example:: .. needpie:: Requirement status :labels: Open, In progress, Closed @@ -92,15 +65,6 @@ values/lines from content. type == 'req' and status == 'in progress' type == 'req' and status == 'closed' -|out| - -.. needpie:: Requirement status - :labels: Open, In progress, Closed - - type == 'req' and status == 'open' - type == 'req' and status == 'in progress' - type == 'req' and status == 'closed' - legend ~~~~~~ @@ -109,9 +73,7 @@ You can place a legend on the right side of the pie chart by setting the ``:lege The ``:legend:`` flag does not support any values. -|ex| - -.. code-block:: rst +.. need-example:: .. needpie:: Requirement status :labels: Open, In progress, Closed @@ -121,16 +83,6 @@ The ``:legend:`` flag does not support any values. type == 'req' and status == 'in progress' type == 'req' and status == 'closed' -|out| - -.. needpie:: Requirement status - :labels: Open, In progress, Closed - :legend: - - type == 'req' and status == 'open' - type == 'req' and status == 'in progress' - type == 'req' and status == 'closed' - explode ~~~~~~~ @@ -142,9 +94,7 @@ The amount of values for ``:explode:`` must match the amount of values / content Useful values for ``:explode:`` are between ``0`` and ``0.3`` -|ex| - -.. code-block:: rst +.. need-example:: .. needpie:: Requirement status :explode: 0,0.2,0 @@ -153,24 +103,13 @@ Useful values for ``:explode:`` are between ``0`` and ``0.3`` type == 'req' and status == 'in progress' type == 'req' and status == 'closed' -|out| - -.. needpie:: Requirement status - :explode: 0,0.2,0 - - type == 'req' and status == 'open' - type == 'req' and status == 'in progress' - type == 'req' and status == 'closed' - shadow ~~~~~~ ``:shadow:`` activates a shadow in the pie chart. It does not support any further values. -|ex| - -.. code-block:: rst +.. need-example:: .. needpie:: Requirement status :explode: 0,0.2,0 @@ -180,16 +119,6 @@ shadow type == 'req' and status == 'in progress' type == 'req' and status == 'closed' -|out| - -.. needpie:: Requirement status - :explode: 0,0.2,0 - :shadow: - - type == 'req' and status == 'open' - type == 'req' and status == 'in progress' - type == 'req' and status == 'closed' - colors ~~~~~~ @@ -200,9 +129,7 @@ for a complete list of color names. But besides names, the ``:colors:`` option also supports hex-values like ``#ffcc00``. -|ex| - -.. code-block:: rst +.. need-example:: .. needpie:: Requirement status :colors: lightcoral, gold, #555555 @@ -211,16 +138,6 @@ But besides names, the ``:colors:`` option also supports hex-values like ``#ffcc type == 'req' and status == 'in progress' type == 'req' and status == 'closed' - -|out| - -.. needpie:: Requirement status - :colors: lightcoral, gold, #555555 - - type == 'req' and status == 'open' - type == 'req' and status == 'in progress' - type == 'req' and status == 'closed' - text_color ~~~~~~~~~~ @@ -228,9 +145,7 @@ text_color .. note:: Setting the ``:text_color:`` option does not change the legend and title color. -|ex| - -.. code-block:: rst +.. need-example:: .. needpie:: Requirement status :text_color: w @@ -239,15 +154,6 @@ text_color type == 'req' and status == 'in progress' type == 'req' and status == 'closed' -|out| - -.. needpie:: Requirement status - :text_color: w - - type == 'req' and status == 'open' - type == 'req' and status == 'in progress' - type == 'req' and status == 'closed' - style ~~~~~ @@ -263,9 +169,7 @@ Useful styles are for example: * dark_background * grayscale -|ex| - -.. code-block:: rst +.. need-example:: .. needpie:: Requirement status :style: Solarize_Light2 @@ -274,16 +178,6 @@ Useful styles are for example: type == 'req' and status == 'in progress' type == 'req' and status == 'closed' -|out| - - -.. needpie:: Requirement status - :style: Solarize_Light2 - - type == 'req' and status == 'open' - type == 'req' and status == 'in progress' - type == 'req' and status == 'closed' - overlapping labels ~~~~~~~~~~~~~~~~~~ @@ -295,9 +189,7 @@ In the past we had overlapping labels. See following diagram. Now overlapping labels are removed, and we automatically add a legend with removed information. -|ex| - -.. code-block:: rst +.. need-example:: .. needpie:: Requirement status :labels: New, Open, In progress, Closed, Outdated, Removed @@ -308,18 +200,3 @@ Now overlapping labels are removed, and we automatically add a legend with remov 5 0 0 - - -|out| - -.. needpie:: Requirement status - :labels: New, Open, In progress, Closed, Outdated, Removed - - 90 - 7 - 6 - 5 - 0 - 0 - - diff --git a/docs/directives/needreport.rst b/docs/directives/needreport.rst index a5e02e217..8cc7ec57b 100644 --- a/docs/directives/needreport.rst +++ b/docs/directives/needreport.rst @@ -31,18 +31,11 @@ You can use the template file to customise the content generated by ``needrepor "report_directive": "admonition", } -|ex| - -.. code-block:: rst +.. need-example:: .. needreport:: :types: -|out| - -.. needreport:: - :types: - Options ------- @@ -55,18 +48,11 @@ types Flag for adding information about the :ref:`needs_types` configuration parameter. The flag does not require any values. -|ex| - -.. code-block:: rst +.. need-example:: .. needreport:: :types: -|out| - -.. needreport:: - :types: - .. _links: @@ -76,18 +62,11 @@ links Flag for adding information about the :ref:`needs_extra_links` configuration parameter. The flag does not require any values. -|ex| - -.. code-block:: rst +.. need-example:: .. needreport:: :links: -|out| - -.. needreport:: - :links: - .. _options: @@ -97,31 +76,17 @@ options Flag for adding information about the :ref:`needs_extra_options` configuration parameter. The flag does not require any values. -|ex| - -.. code-block:: rst +.. need-example:: .. needreport:: :options: -|out| - -.. needreport:: - :options: - usage ~~~~~ Flag for adding information about all the ``need`` objects in the current project. The flag does not require any values. -|ex| - -.. code-block:: rst +.. need-example:: .. needreport:: :usage: - -|out| - -.. needreport:: - :usage: diff --git a/docs/directives/needsequence.rst b/docs/directives/needsequence.rst index 9b42c6aa0..27c4ed231 100644 --- a/docs/directives/needsequence.rst +++ b/docs/directives/needsequence.rst @@ -7,20 +7,12 @@ needsequence ``needsequence`` adds a sequence-chart to your documentation. -|ex| - -.. code-block:: rst +.. need-example:: .. needsequence:: My sequence chart :start: USER_A, USER_D :link_types: links, triggers -|out| - -.. needsequence:: My sequence chart - :start: USER_A, USER_D - :link_types: links, triggers - .. dropdown:: Show the needs used in the above example .. user:: Mr. A @@ -157,18 +149,9 @@ Default: None (no active filtering) You can use this function to filter out a specific participant. As an example, we use the same ``needsequence`` from the beginning, but without ``USER_C / Expert``: -|ex| - -.. code-block:: rst +.. need-example:: .. needsequence:: My filtered sequence chart :start: USER_A, USER_D :link_types: links, triggers :filter: "Expert" not in title - -|out| - -.. needsequence:: My filtered sequence chart - :start: USER_A, USER_D - :link_types: links, triggers - :filter: "Expert" not in title \ No newline at end of file diff --git a/docs/directives/needservice.rst b/docs/directives/needservice.rst index e9d43b2ac..c5bb34679 100644 --- a/docs/directives/needservice.rst +++ b/docs/directives/needservice.rst @@ -4,9 +4,7 @@ needservice =========== .. versionadded:: 0.6.0 -``needservice`` allows the import of data from external services like GitHub. - -|ex| +``needservice`` allows the import of data from external services like GitHub, for example: .. code-block:: rst @@ -47,9 +45,7 @@ debug ~~~~~ Set ``debug`` to get debug-output of the ``needservice`` only. No needs will be created. -Useful to understand the return values of services or to figure out, why a connection can not be established. - -|ex| +Useful to understand the return values of services or to figure out, why a connection can not be established, for example: .. code-block:: rst @@ -74,24 +70,11 @@ For details, please take a look into its specific documentation under :ref:`gith The service queries ``GitHub`` for issues in the **Sphinx-Needs** repository that have *node* and *latexpdf* in their content. -|ex| +.. tip:: Click the small arrow under the need id to see all meta data. -.. code-block:: rst +.. need-example:: .. needservice:: github-issues :query: repo:useblocks/sphinx-needs node latexpdf :max_content_lines: 4 :id_prefix: EXAMPLE_ - - -Click the small arrow under the need id to see all meta data. - -|out| - -.. needservice:: github-issues - :query: repo:useblocks/sphinx-needs node latexpdf - :max_amount: 1 - :id_prefix: EXAMPLE_ - :max_content_lines: 4 - - diff --git a/docs/directives/needtable.rst b/docs/directives/needtable.rst index 8e26f9f11..8eed70d11 100644 --- a/docs/directives/needtable.rst +++ b/docs/directives/needtable.rst @@ -7,20 +7,12 @@ needtable **needtable** generates a table, based on the result of given filters. -|ex| - -.. code-block:: rst +.. need-example:: .. needtable:: Example table :tags: main_example :style: table -|out| - -.. needtable:: Example table - :tags: main_example - :style: table - We use the argument of a ``needtable`` as caption for the table. Options @@ -45,21 +37,10 @@ For instance:: This will show the columns *id*, *title* and *tags* in the order given. -.. dropdown:: Show example - - |ex| - - .. code-block:: rst - - .. needtable:: - :columns: id;title;tags - - |out| +.. need-example:: .. needtable:: - :tags: test :columns: id;title;tags - :style: table You can set all options of a need (incl. :ref:`needs_extra_options`) as a column. This also includes internal options like ``docname`` (Use `:layout: debug` on a need for a complete list) @@ -70,16 +51,20 @@ Tables with a lot of columns will get a horizontal scrollbar in HTML output. **DataTable style** -.. needtable:: - :tags: test - :columns: id;title;tags;status;docname;lineno,is_external,is_need;is_part;content +.. need-example:: + + .. needtable:: + :tags: test + :columns: id;title;tags;status;docname;lineno,is_external,is_need;is_part;content **Normal style** -.. needtable:: - :tags: test - :style: table - :columns: id;title;tags;status;docname;lineno,is_external,is_need;is_part;content +.. need-example:: + + .. needtable:: + :tags: test + :style: table + :columns: id;title;tags;status;docname;lineno,is_external,is_need;is_part;content .. _needtable_colwidths: @@ -93,9 +78,7 @@ A comma separated list of lengths or percentages used to define the width of eac It has the same meaning as the ``width options`` of `listtable `_ directive. -|ex| - -.. code-block:: rst +.. need-example:: .. needtable:: :tags: test @@ -103,15 +86,6 @@ It has the same meaning as the ``width options`` of :colwidths: 50,40,10 :style: table -|out| - -.. needtable:: - :tags: test - :columns: id,title,status - :colwidths: 50,40,10 - :style: table - - .. _needtable_custom_titles: Custom column titles @@ -119,25 +93,13 @@ Custom column titles You can customize each column title by following this syntax for its definition: ``OPTION as "My custom title"``. The characters ``,`` or ``;`` are not allowed. -.. dropdown:: Show example - - |ex| - - .. code-block:: rst - - .. needtable:: - :tags: test - :columns: id;title as "Headline"; tags as "Labels" - :style: table - - |out| +.. need-example:: .. needtable:: :tags: test :columns: id;title as "Headline"; tags as "Labels" :style: table - .. _needtable_show_filters: show_filters @@ -145,19 +107,7 @@ show_filters If set, we add the used filter above the table: -.. dropdown:: Show example - - |ex| - - .. code-block:: rst - - .. needtable:: - :tags: test - :columns: id;title;tags - :show_filters: - :style: table - - |out| +.. need-example:: .. needtable:: :tags: test @@ -165,7 +115,6 @@ If set, we add the used filter above the table: :show_filters: :style: table - .. _needtable_style: style @@ -181,9 +130,7 @@ Overrides config parameter :ref:`needs_table_style` if set. .. dropdown:: Show example - |ex| - - .. code-block:: rst + .. need-example:: .. needtable:: :style: table @@ -191,20 +138,6 @@ Overrides config parameter :ref:`needs_table_style` if set. .. needtable:: :style: datatables - Table with ``:style: table``: - - |out| - - .. needtable:: - :tags: awesome - :style: table - - Table with ``:style: datatables``: - - .. needtable:: - :tags: awesome - :style: datatables - .. _needtable_show_parts: show_parts @@ -218,21 +151,18 @@ It adds the part rows directly under the related need’s row, and their id and To change the prefix please read :ref:`needs_part_prefix`. -|ex| - -.. needtable:: - :tags: test_table - :filter: is_need - :show_parts: - :columns: id;title;outgoing;incoming - :style: table - +.. need-example:: + .. needtable:: + :tags: test_table + :filter: is_need + :show_parts: + :columns: id;title;outgoing;incoming + :style: table .. dropdown:: Show above example's configuration - .. code-block:: rst - + .. need-example:: .. req:: Test need with need parts :id: table_001 @@ -251,34 +181,6 @@ To change the prefix please read :ref:`needs_part_prefix`. :id: table_003 :links: table_001.2 - .. needtable:: - :filter: is_need - :show_parts: - :columns: id;title;outgoing;incoming - :style: table - - - .. req:: Test need with need parts - :id: table_001 - :tags: test_table - - :np:`(1) Part 1 of requirement`. - - :np:`(2) Part 2 of requirement`. - - :np:`(3) Part 3 of requirement`. - - - .. spec:: Specifies part 1 - :id: table_002 - :tags: test_table - :links: table_001.1 - - .. spec:: Specifies part 2 - :id: table_003 - :tags: test_table - :links: table_001.2 - .. _needtable_style_row: style_row @@ -290,20 +192,12 @@ You can use the ``style_row`` option to set a specific class-attribute for the t Also, you can set specific layout for the row. -|ex| - -.. code-block:: rst +.. need-example:: .. needtable:: :tags: ex_row_color :style_row: needs_blue_border -|out| - -.. needtable:: - :tags: ex_row_color - :style_row: needs_blue_border - Row style based on specific need value ...................................... @@ -311,12 +205,12 @@ Row style based on specific need value You can use :ref:`dynamic_functions` to derive the value for ``style_row`` based on a specific value of the documented need in the row. -|ex| +.. need-example:: -.. needtable:: - :tags: ex_row_color - :columns: id, title, status - :style_row: needs_[[copy("status")]] + .. needtable:: + :tags: ex_row_color + :columns: id, title, status + :style_row: needs_[[copy("status")]] In this example we set ``style_row`` to ``needs_[[copy("status")]]``, so the status of each need will be part of the row style. @@ -393,20 +287,22 @@ Option to sort the filtered-results based on a key. The sort-value must be compatible with the options supported by the :ref:`filter_string`, and the addressed need-value must have the type ``string``, ``float`` or ``int``. -|ex| - By default, we use ``id_complete`` if we don't set a sort option. -.. needtable:: - :tags: ex_row_color - :style: table +.. need-example:: + + .. needtable:: + :tags: ex_row_color + :style: table In this case, we set the sort option to ``status``. So *EX_ROW_3* is above of *EX_ROW_2*. -.. needtable:: - :tags: ex_row_color - :style: table - :sort: status +.. need-example:: + + .. needtable:: + :tags: ex_row_color + :style: table + :sort: status .. dropdown:: Show used configuration @@ -436,34 +332,21 @@ class You can set additional class-names for a ``needtable`` using the ``class`` option. Mostly used for HTML output. It supports comma separated values and will add classes to the already set classes by Sphinx-Needs. -|ex| - -.. rubric:: rst file: - -.. code-block:: rst - - .. needtable:: - :tags: test - :columns: id,title,status - :style: table - :class: class_red_border - -.. rubric:: custom css file: - .. code-block:: css + :caption: custom.css table.class_red_border { border: 3px solid red; } -|out| +.. need-example:: -.. needtable:: - :tags: test - :columns: id,title,status - :style: table - :class: class_red_border + .. needtable:: + :tags: test + :columns: id,title,status + :style: table + :class: class_red_border common filters ~~~~~~~~~~~~~~ diff --git a/docs/directives/needuml.rst b/docs/directives/needuml.rst index d5683b2cb..d1d293e38 100644 --- a/docs/directives/needuml.rst +++ b/docs/directives/needuml.rst @@ -12,9 +12,7 @@ So it allows to define PlantUML diagrams. But gives you access to need object data by supporting `Jinja `_ statements, which allows you to use loops, if-clauses, and it injects data from need-objects. -|ex| - -.. code-block:: rst +.. need-example:: .. needuml:: @@ -42,36 +40,6 @@ which allows you to use loops, if-clauses, and it injects data from need-objects card {{needs['COMP_NEEDUML2'].status}} } - -|out| - -.. needuml:: - - {{uml('FEATURE_NEEDUML1')}} - {{uml('COMP_NEEDUML2')}} - -.. feature:: NeedUml example need - :id: FEATURE_NEEDUML1 - :tags: needuml - :status: draft - - Example Need for NeedUml. - -.. comp:: NeedUml example need 2 - :id: COMP_NEEDUML2 - :tags: needuml - :status: draft - - Second example Need for NeedUml. - - .. needuml:: - - {{flow('COMP_NEEDUML2')}} { - card implement - card {{needs['COMP_NEEDUML2'].status}} - } - - .. _needuml_options: Options @@ -85,9 +53,7 @@ extra Allows to inject additional key-value pairs into the ``needuml`` rendering. ``:extra:`` must be a comma-separated list, containing *key:value* pairs. -|ex| - -.. code-block:: rst +.. need-example:: .. needuml:: :extra: name:Roberto,work:RocketLab @@ -96,15 +62,6 @@ Allows to inject additional key-value pairs into the ``needuml`` rendering. card "{{work}}" as b a -> b -|out| - -.. needuml:: - :extra: name:Roberto,work:RocketLab - - card "{{name}}" as a - card "{{work}}" as b - a -> b - .. note:: ``:extra:`` values are only available in the current PlantUML code. @@ -133,9 +90,7 @@ If ``:debug:`` is set, a debug-output of the generated PlantUML code gets added Helpful to identify reasons why a PlantUML build may have thrown errors. -|ex| - -.. code-block:: rst +.. need-example:: .. needuml:: :debug: @@ -144,16 +99,6 @@ Helpful to identify reasons why a PlantUML build may have thrown errors. card "Peter" } -|out| - -.. needuml:: - :debug: - - node "RocketLab" { - card "Peter" - } - - .. _needuml_key: key @@ -163,9 +108,7 @@ Allows to store multiple ``needuml`` inside a need under ``arch`` under the give If no option key given, then the first ``needuml`` will be stored in the need under ``arch`` under ``diagram``, ``need["arch"]["diagram"]``. Option ``:key:`` value can't be empty, and can't be ``diagram``. -|ex| - -.. code-block:: rst +.. need-example:: .. comp:: Component Y :id: COMP_002 @@ -179,38 +122,13 @@ Option ``:key:`` value can't be empty, and can't be ``diagram``. .. needuml:: :key: class - class System_A as A { - todo - open - } + class Foo .. needuml:: B -> C: Hi C -> B: Hi there -|out| - -.. comp:: Component Y - :id: COMP_002 - - .. needuml:: - :key: sequence - - Alice -> Bob: Hi Bob - Bob --> Alice: Hi Alice - - .. needuml:: - :key: class - - class Foo - - .. needuml:: - - B -> C: Hi - C -> B: Hi there - - .. _needuml_save: save @@ -224,9 +142,7 @@ using builder :ref:`needumls_builder` or other builder like `html` with configur If given file path already exists, it will be overwritten. -|ex| - -.. code-block:: rst +.. need-example:: .. int:: Test needuml save :id: INT_001 @@ -240,17 +156,6 @@ If given file path already exists, it will be overwritten. In this example, if builder :ref:`needumls_builder` is used, the plantuml-code will be exported to file at `outdir` of current builder, e.g. `_build/needumls/needuml_group_A/my_needuml.puml`. -|out| - -.. int:: Test needuml save - :id: INT_001 - - .. needuml:: - :save: needuml_group_A/my_needuml.puml - - Alice -> Bob: Hi Bob - Bob --> Alice: Hi Alice - .. _needuml_jinja: @@ -265,20 +170,12 @@ needs ~~~~~ A Python dictionary containing all Needs. The ``need_id`` is used as key. -|ex| - -.. code-block:: rst +.. need-example:: .. needuml:: node "{{needs["FEATURE_NEEDUML1"].title}}" -|out| - -.. needuml:: - - node "{{needs["FEATURE_NEEDUML1"].title}}" - .. _needuml_jinja_flow: @@ -298,9 +195,7 @@ This functions represents each Need the same way. E.g. see even the following example, with text following `{{flow("COMP_001")}}`. -|ex| - -.. code-block:: rst +.. need-example:: .. needuml:: @@ -310,25 +205,13 @@ This functions represents each Need the same way. } -|out| - -.. needuml:: - - {{flow("FEATURE_NEEDUML1")}} - {{flow("COMP_001")}} { - card manuall_written - } - - .. _needuml_jinja_filter: filter(filter_string) ~~~~~~~~~~~~~~~~~~~~~ Finds a list of Sphinx-Need objects that pass the given filter string. -|ex| - -.. code-block:: rst +.. need-example:: .. needuml:: @@ -336,14 +219,6 @@ Finds a list of Sphinx-Need objects that pass the given filter string. node "{{need.title}}" {% endfor %} -|out| - -.. needuml:: - - {% for need in filter("type == 'int' and status != 'open'") %} - node "{{need.title}}" - {% endfor %} - .. _needuml_jinja_ref: @@ -355,22 +230,13 @@ text associated to the hyperlink is either defined by `option` (in this case, Sphinx-Need picks the text of the field specified by `option`), or by the free text `text`. -|ex| - -.. code-block:: rst +.. need-example:: .. needuml:: Alice -> Bob: {{ref("FEATURE_1", option="title")}} Bob -> Alice: {{ref("FEATURE_2", text="A completely free text")}} -|out| - -.. needuml:: - - Alice -> Bob: {{ref("FEATURE_1", option="title")}} - Bob -> Alice: {{ref("FEATURE_2", text="A completely free text")}} - .. _needuml_jinja_uml: uml(id) @@ -382,9 +248,7 @@ If diagram code is available in the need data under ``arch``, the stored PlantUM Please read :ref:`need_diagram` for details. -|ex| - -.. code-block:: rst +.. need-example:: .. needuml:: @@ -393,15 +257,6 @@ Please read :ref:`need_diagram` for details. {{uml("COMP_001")}} {{uml("FEATURE_NEEDUML1")}} -|out| - -.. needuml:: - - allowmixing - - {{uml("COMP_001")}} - {{uml("FEATURE_NEEDUML1")}} - .. _needuml_jinja_uml_key: @@ -412,9 +267,7 @@ Key argument ``key`` value by default is ``diagram``. If no key argument given, then the PlantUML code is loaded from ``diagram`` under ``arch`` inside the need object. -|ex| - -.. code-block:: rst +.. need-example:: .. comp:: Z :id: COMP_Z @@ -423,15 +276,6 @@ inside the need object. {{uml('COMP_002', 'sequence')}} -|out| - -.. comp:: Z - :id: COMP_Z - - .. needuml:: - - {{uml('COMP_002', 'sequence')}} - .. _needuml_jinja_uml_args: @@ -440,9 +284,7 @@ Additional keyword arguments :ref:`uml() ` supports additional keyword parameters which are then available in the loaded PlantUML code. -|ex| - -.. code-block:: rst +.. need-example:: .. comp:: Variant A or B :id: COMP_A_B @@ -462,63 +304,25 @@ Additional keyword arguments By default **Unknown** is shown, as no variant was set. -|out| - -.. comp:: Variant A or B - :id: COMP_A_B - - .. needuml:: - - {% if variant == "A" %} - class "A" as cl - {% elif variant == "B" %} - class "B" as cl { - attribute_x - function_x() - } - {% else %} - class "Unknown" as cl - {% endif %} - - By default **Unknown** is shown, as no variant was set. - Passing ``variant="A"`` parameter to the :ref:`uml() ` function, we get the following: -|ex| - -.. code-block:: rst +.. need-example:: .. needuml:: :debug: {{uml("COMP_A_B", variant="A")}} -|out| - -.. needuml:: - :debug: - - {{uml("COMP_A_B", variant="A")}} - Passing ``variant="B"`` parameter to the :ref:`uml() ` function, we get the following: -|ex| - -.. code-block:: rst +.. need-example:: .. needuml:: :debug: {{uml("COMP_A_B", variant="B")}} -|out| - -.. needuml:: - :debug: - - {{uml("COMP_A_B", variant="B")}} - .. _needuml_jinja_uml_chain: @@ -639,65 +443,35 @@ All features are available and ``uml()`` can be used multiple time on different NeedUml Examples ---------------- -|ex| - -.. code-block:: rst +.. need-example:: .. needuml:: + :scale: 50% + :align: right allowmixing class "Sphinx-Needs" as sn { - requirements - specifications - test_cases - customize() - automate() - export() + requirements + specifications + test_cases + customize() + automate() + export() } {% set ids = ["FEATURE_1", "FEATURE_5", "FEATURE_7"]%} {% for need in needs.values() %} - {% if need.id in ids %} - card "{{need['title']}}" as need_{{loop.index}} #ffcc00 - need_{{loop.index}} --> sn - {% endif %} + {% if need.id in ids %} + card "{{need['title']}}" as need_{{loop.index}} #ffcc00 + need_{{loop.index}} --> sn + {% endif %} {% endfor %} card "and much more..." as much #ffcc00 much -> sn -|out| - -.. needuml:: - :scale: 50% - :align: right - - allowmixing - - class "Sphinx-Needs" as sn { - requirements - specifications - test_cases - customize() - automate() - export() - } - - {% set ids = ["FEATURE_1", "FEATURE_5", "FEATURE_7"]%} - {% for need in needs.values() %} - {% if need.id in ids %} - card "{{need['title']}}" as need_{{loop.index}} #ffcc00 - need_{{loop.index}} --> sn - {% endif %} - {% endfor %} - - card "and much more..." as much #ffcc00 - much -> sn - -|ex| - -.. code-block:: rst +.. need-example:: .. comp:: Component X :id: COMP_001 @@ -718,27 +492,3 @@ NeedUml Examples } class_x o-- class_y - -|out| - -.. comp:: Component X - :id: COMP_001 - - .. needuml:: - - class "Class X" as class_x { - attribute_1 - attribute_2 - function_1() - function_2() - function_3() - } - - class "Class Y" as class_y { - attribute_1 - function_1() - } - - class_x o-- class_y - - diff --git a/docs/roles.rst b/docs/roles.rst index 9bb4c7493..7c8e8d2cc 100644 --- a/docs/roles.rst +++ b/docs/roles.rst @@ -5,13 +5,8 @@ Roles You can use Roles to get short information of needs inside single sentences. -|ex| - -.. code-block:: rst - - My specification :need:`my_spec` is used to fulfill requirements :need_incoming:`my_spec` - .. _role_need: +.. _needref: need ---- @@ -22,32 +17,17 @@ We use it to reference an existing need, without the need to keep title and link With ``[[`` and ``]]`` you can refer to defined and set :ref:`extra options `. -Example -~~~~~~~ - -.. req:: Sliced Bread - :id: roles_req_1 - :status: open - :value: 20 - :unit: slices - -.. _needref: +.. need-example:: -|ex| - -.. code-block:: rst - - The requirement :need:`roles_req_1` is the most important one. - - But we can also set :need:`a custom link name `. - - And we can change the text even more e.g. :need:`[[value]] [[unit]] of [[title]] ([[id]] [[status]]) `. - -|out| + .. req:: Sliced Bread + :id: roles_req_1 + :status: open + :value: 20 + :unit: slices -| The requirement :need:`roles_req_1` is the most important one. -| But we can also set :need:`a custom link name `. -| And we can change the text even more e.g. :need:`[[value]] [[unit]] of [[title]] ([[id]] [[status]]) `. + | The requirement :need:`roles_req_1` is the most important one. + | But we can also set :need:`a custom link name `. + | And we can change the text even more e.g. :need:`[[value]] [[unit]] of [[title]] ([[id]] [[status]]) `. .. note:: @@ -75,24 +55,14 @@ need_outgoing ``:need_outgoing:`` adds a list of all outgoing links of the given need. The list contains the need IDs only, no title or any other information is printed. -Example -~~~~~~~ +.. need-example:: -.. req:: Butter on Bread - :id: roles_req_2 - :links: roles_req_1 - -|ex| - -.. code-block:: jinja + .. req:: Butter on Bread + :id: roles_req_2 + :links: roles_req_1 To get butter on our bread, we need to fulfill :need_outgoing:`roles_req_2` -|out| - -To get butter on our bread, we need to fulfill :need_outgoing:`roles_req_2` - - .. _role_need_incoming: need_incoming @@ -101,22 +71,11 @@ need_incoming ``:need_incoming:`` prints a list of IDs of needs which have set outgoing links to the given need. -Example -~~~~~~~ - -|ex| - -.. code-block:: jinja +.. need-example:: The realisation of **Sliced Bread** is really important because the needs :need_incoming:`roles_req_1` are based on it. -|out| - -The realisation of **Sliced Bread** is really important because the -needs :need_incoming:`roles_req_1` are based on it. - - .. _need_part: need_part / np @@ -128,12 +87,7 @@ This sub-ids can be linked and referenced in other need functions like links and The used need_part id can be freely chosen, but should not contain any whitespaces or dots. -Example -~~~~~~~ - -|ex| - -.. code-block:: rst +.. need-example:: .. req:: Car must be awesome :id: my_car_1 @@ -160,58 +114,21 @@ Example Reference to a part of a need from outside need scope: :need:`my_car_1.2`. -|out| - -.. req:: Car must be awesome - :id: my_car_1 - :tags: car - :status: open - - My new car must be the fastest on the world. Therefor it shall have: - - * :need_part:`(1) A top speed of 300 km/h` - * :np:`(2) An acceleration of 200 m/s² or much much more` - - And we also need --> :np:`(awesome_3) a turbo button`! - - -.. spec:: Build awesome car - :id: impl_my_car_1 - :links: my_car_1, my_car_1.1, my_car_1.2 - :tags: car - - Requirements :need:`my_car_1.1` and :need:`my_car_1.2` are no problem and can - be realised by doing rocket science. - - But no way to get :need:`my_car_1.awesome_3` realised. - - -Reference to a part of a need from outside need scope: :need:`my_car_1.2`. - **Presentation in needflow** Links to need_parts are shown as dotted line to the upper need inside :ref:`needflow` diagrams. They are also getting the part_id as link description. -|ex| - -.. code-block:: rst +.. need-example:: .. needflow:: :filter: id in ["my_car_1","impl_my_car_1"] -|out| - -.. needflow:: - :filter: id in ["my_car_1","impl_my_car_1"] - **Presentation in needtable** Please see :ref:`needtable_show_parts` of :ref:`needtable` configuration documentation. -|ex| - -.. code-block:: rst +.. need-example:: .. needtable:: :style: table @@ -219,14 +136,6 @@ Please see :ref:`needtable_show_parts` of :ref:`needtable` configuration documen :show_parts: :columns: id, title, incoming, outgoing -|out| - -.. needtable:: - :style: table - :filter: 'car' in tags and is_need - :show_parts: - :columns: id, title, incoming, outgoing - .. _need_count: need_count @@ -238,30 +147,15 @@ Counts found needs for a given filter and shows the final amount. The content of the role must be a valid filter-string as used e.g. by :ref:`needlist` in the ``:filter:`` option. See :ref:`filter_string` for more information. -Example -~~~~~~~ - -|ex| - -.. code-block:: rst - - All needs: :need_count:`True` - Specification needs: :need_count:`type=='spec'` - Open specification needs: :need_count:`type=='spec' and status=='open'` - Needs with tag *test*: :need_count:`'test' in tags` - Needs with title longer 10 chars: :need_count:`search("[\\w\\s]{10,}", title)` - All need_parts: :need_count:`is_part` - All needs containing need_parts: :need_count:`is_need and len(parts)>0` - -|out| +.. need-example:: -| All needs: :need_count:`True` -| Specification needs: :need_count:`type=='spec'` -| Open specification needs: :need_count:`type=='spec' and status=='open'` -| Needs with tag *test*: :need_count:`'test' in tags` -| Needs with title longer 10 chars: :need_count:`search("[\\w\\s]{10,}", title)` -| All need_parts: :need_count:`is_part` -| All needs containing need_parts: :need_count:`is_need and len(parts)>0` + | All needs: :need_count:`True` + | Specification needs: :need_count:`type=='spec'` + | Open specification needs: :need_count:`type=='spec' and status=='open'` + | Needs with tag *test*: :need_count:`'test' in tags` + | Needs with title longer 10 chars: :need_count:`search("[\\w\\s]{10,}", title)` + | All need_parts: :need_count:`is_part` + | All needs containing need_parts: :need_count:`is_need and len(parts)>0` .. note:: @@ -285,15 +179,9 @@ Ratio To calculate the ratio of one filter to another filter, you can define two filters separated by ``_?_`` (question mark surrounded by one space on each side). -|ex| +.. need-example:: -.. code-block:: rst - - :need_count:`status = open and type == "spec" ? type == "spec"` % of our specifications are open. - -|out| - -:need_count:`status == "open" and type == "spec" ? type == "spec"` % of our specifications are open. + :need_count:`status == open and type == "spec" ? type == "spec"` % of our specifications are open. .. _need_func: @@ -304,12 +192,6 @@ need_func Executes :ref:`dynamic_functions` and uses the return values as content. -|ex| - -.. code-block:: rst +.. need-example:: A nice :need_func:`[[echo("first")]] test` for need_func. - -|out| - -A nice :need_func:`[[echo("first")]] test` for need_func.