Adds links_down and meta-data handling to list2need (#856)

* Adds links_down to list2need. Tests missing * Docs for links-down and meta-data support. Tests missing * list2need tests for links-down and options * Typing fixes * flake8: ignoring B028, using ! r * Bugfix for type annotation
useblocks · Jan 17, 2023 · 63d9b2b · 63d9b2b
1 parent 8334b84
commit 63d9b2b
Show file tree

Hide file tree

Showing 9 changed files with 285 additions and 65 deletions.
diff --git a/.flake8 b/.flake8
@@ -1,3 +1,3 @@
 [flake8]
 max-line-length = 120
-extend-ignore = E501, E203
+extend-ignore = E501, E203, B028
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,11 +1,11 @@
 repos:
   - repo: https://github.com/psf/black
-    rev: 22.3.0
+    rev: 22.12.0
     hooks:
       - id: black
 
   - repo: https://github.com/PyCQA/flake8
-    rev: 3.9.2
+    rev: 6.0.0
     hooks:
       - id: flake8
         additional_dependencies:
@@ -15,12 +15,12 @@ repos:
           - pep8-naming
 
   - repo: https://github.com/pycqa/isort
-    rev: 5.10.1
+    rev: 5.11.4
     hooks:
       - id: isort
 
   - repo: https://github.com/asottile/pyupgrade
-    rev: v2.32.1
+    rev: v3.3.1
     hooks:
       - id: pyupgrade
         args:
@@ -36,6 +36,6 @@ repos:
         pass_filenames: false
 
   - repo: https://github.com/python-poetry/poetry
-    rev: 1.2.1
+    rev: 1.3.0
     hooks:
       - id: poetry-check
diff --git a/docs/directives/list2need.rst b/docs/directives/list2need.rst
@@ -21,6 +21,10 @@ Need-IDs get generated automatically (hash value), if not given.
 IDs can be set by the prefix ``(ID)`` in the line. Example: ``(REQ-1)My first requirement``.
 This mechanism is the same as the one used by :ref:`need_part`.
 
+Options for the need-objects can be set by adding them like ``((status="open"))``.
+For details please see :ref:`list2need_meta_data`.
+
+
 .. code-block:: rst
 
    .. list2need::
@@ -30,20 +34,21 @@ This mechanism is the same as the one used by :ref:`need_part`.
 
       * Need example on level 1
       * (NEED-002) Another Need example on level 1 with a given ID
-        * Sub-Need on level 2
+        * Sub-Need on level 2 with status option set
         * Another Sub-Need on level 2. Where this sentence will be used
           as content, the first one as title.
           * Sub-Need on level 3. With some rst-syntax support for
             the **content** by :ref:`list2need`
 
+
 .. list2need::
    :types: req, spec, test
    :presentation: nested
    :delimiter: .
 
    * Need example on level 1
    * (NEED-002) Another Need example on level 1 with a given ID
-     * Sub-Need on level 2
+     * Sub-Need on level 2 with status option set ((status='open'))
      * Another Sub-Need on level 2. Where this sentence will be used
        as content, the first one as title.
        * Sub-Need on level 3. With some rst-syntax support for
@@ -69,6 +74,26 @@ So it can be used to structure longer titles or content, and has no impact on th
 Options
 -------
 
+types
+~~~~~
+
+List of need-types, which are used for the different list-levels.
+As input name the ``directive`` entry from the configuration variable  :ref:`needs_types` is used.
+
+There is no default value and ``types`` must be set.
+
+.. code-block:: rst
+
+      .. list2need::
+         :types: feature, function, test
+
+         * Login user
+           * Provide login screen
+           * Create password hash
+             * Recalculate hash and compare
+
+
+
 presentation
 ~~~~~~~~~~~~
 Defines how the single Sphinx-Needs objects shall be presented.
@@ -89,6 +114,41 @@ The first split part is used as title, the rest as content.
 
 Default: **.**
 
+links-down
+~~~~~~~~~~
+``links-down`` set automatically links between the different levels of the list.
+
+.. code-block:: rst
+
+   .. list2need::
+      :types: req, spec, test
+      :presentation: standalone
+      :links-down: triggers, tests
+
+      * (NEED-A)Login user
+        * (NEED-B)Provide login screen
+        * (NEED-C)Create password hash
+          * (NEED-D)Recalculate hash and compare
+
+``:links-down: triggers, tests`` will set a link from type ``triggers`` from ``NEED-A`` to ``NEED-B`` and ``NEED-C``.
+``NEED-C`` will get a link from type ``tests`` to ``NEED-D``.
+
+So links get set from the upper level down to all need-objects on the direct lower level (top-down approach).
+
+The amount of given link-types must be the amount of used levels minus 1.
+
+**Result from the above example**:
+
+.. list2need::
+   :types: req, spec, test
+   :presentation: standalone
+   :links-down: triggers, tests
+
+   * (NEED-A)Login user
+     * (NEED-B)Provide login screen
+     * (NEED-C)Create password hash
+       * (NEED-D)Recalculate hash and compare
+
 
 List examples
 -------------
@@ -224,55 +284,44 @@ Lists with need-part support
      * And a spec need.
        Lets reference a need-part frm above: :need:`LIST2NEED-REQ-1.1`
 
+.. _list2need_meta_data:
+
 Set meta-data
 ~~~~~~~~~~~~~
-To set also meta-data for selected needs created by :ref:`list2need`, you can use
-:ref:`needextend` in a second step.
+Meta-data can be set directly in the related line via: ``((status="open"))``.
+Or if the amount of option/values is getting too complex, in a second step
+by using :ref:`needextend`.
+
+The position of the option-string inside the line is not important.
+Multiple options need to be separated by ``,``.
+And instead of ``"`` also ``'`` can be used.
 
 .. code-block:: rst
 
    .. list2need::
       :types: feature, req
 
-      * (EXT-FEATURE-A)Feature A
-        * (EXT-REQ-1)Requirement 1. It shall be fast.
-        * (EXT-REQ-2)Requirement 2. It shall be big.
-      * (EXT-FEATURE-B)Feature B
-
-
-   .. needextend:: EXT-REQ-1
-      :status: closed
-      :style: green_border
+   * (EXT-FEATURE-A)Feature A
+     * (EXT-REQ-1)Requirement 1. It shall be fast. ((tags="A, fast", style="green_border"))
+     * (EXT-REQ-2)Requirement 2. It shall be big. ((tags="A, big", style="red_border"))
+   * (EXT-FEATURE-B)Feature B.
+     Options are given in next line for readability
+     ((status="done", tags="B", links="EXT-FEATURE-A"))
 
-   .. needextend:: EXT-REQ-2
-      :status: open
-      :style: red_border
+   .. needextend:: EXT-FEATURE-B
+      :style: yellow
 
-   .. needextend:: id in ["EXT-FEATURE-A", "EXT-FEATURE-B"]
-      :tags: fast, big
 
-   .. needextend:: EXT-FEATURE-B
-      :links: EXT-FEATURE-A
 
 .. list2need::
    :types: feature, req
 
    * (EXT-FEATURE-A)Feature A
-     * (EXT-REQ-1)Requirement 1. It shall be fast.
-     * (EXT-REQ-2)Requirement 2. It shall be big.
-   * (EXT-FEATURE-B)Feature B
-
-
-.. needextend:: EXT-REQ-1
-   :status: closed
-   :style: green_border
-
-.. needextend:: EXT-REQ-2
-   :status: open
-   :style: red_border
-
-.. needextend:: id in ["EXT-FEATURE-A", "EXT-FEATURE-B"]
-   :tags: fast, big
+     * (EXT-REQ-1)Requirement 1. It shall be fast. ((tags="A, fast", style="green_border"))
+     * (EXT-REQ-2)Requirement 2. It shall be big. ((tags="A, big", style="red_border"))
+   * (EXT-FEATURE-B)Feature B.
+     Options are given in next line for readability
+     ((status="done", tags="B", links="EXT-FEATURE-A"))
 
 .. needextend:: EXT-FEATURE-B
-   :links: EXT-FEATURE-A
+   :style: yellow