From 36c0bb8ea7d5cbc1b454256a12acb62c449851bf Mon Sep 17 00:00:00 2001 From: Randy Duodu Date: Tue, 24 Jan 2023 09:44:29 +0000 Subject: [PATCH] Updated the collapsible containers and minor changes (#857) --- docs/_static/custom.css | 17 ++- docs/changelog.rst | 6 +- docs/conf.py | 13 +-- docs/configuration.rst | 43 ++----- docs/directives/needgantt.rst | 36 +----- docs/directives/needimport.rst | 2 +- docs/directives/needlist.rst | 18 +-- docs/directives/needsequence.rst | 108 +++++++++--------- docs/directives/needtable.rst | 42 ++----- docs/directives/needuml.rst | 4 +- docs/examples/index.rst | 4 +- docs/filter.rst | 38 ++---- docs/needs_templates/report_template.need | 15 +-- docs/services/open_needs.rst | 6 +- .../directives/needreport_template.rst | 20 +--- sphinx_needs/layout.py | 32 ++++-- 16 files changed, 147 insertions(+), 257 deletions(-) diff --git a/docs/_static/custom.css b/docs/_static/custom.css index 967f14c2e..1de3a1e16 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -14,16 +14,20 @@ div.need_container { div.wy-table-responsive { width: 100% !important; } -table.need { +table.need, .md-typeset table.data:not(.plain) { display: table !important; width: 100% !important; } -.md-typeset, .md-nav, .md-typeset table:not([class]) { +.md-typeset, .md-nav, .md-typeset table:not([class]), +.md-typeset table.data:not(.plain){ font-size: 16px !important; line-height: 1.5 !important; } +table { + border: 1px solid #e1e4e5 !important; +} h1, h2, h3 { font-family: 'Recursive', sans-serif !important; @@ -46,6 +50,10 @@ h3 { margin-bottom: 10px !important; } +.md-typeset :is(.admonition,details) { + font-size: 14px; +} + .underline { text-decoration: underline; } @@ -58,7 +66,7 @@ h3 { --img-filter: brightness(0) invert(1); } -img.needs-logo-big { +img.needs-logo-big, img.sn_collapse_img { filter: var(--img-filter); } @@ -170,4 +178,7 @@ div.dt-button-collection button.dt-button.active:not(.disabled) { .md-header__button.md-logo :is(img, png) { height: 2.2rem !important; +} +details.sd-dropdown .sd-summary-up, details.sd-dropdown .sd-summary-down { + display: none; } \ No newline at end of file diff --git a/docs/changelog.rst b/docs/changelog.rst index efb88dc84..872d4a7a0 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -654,7 +654,7 @@ custom css definitions you need to update them. 0.2.0 ----- -* Deprecated: :ref:`needfilter` is replaced by :ref:`needlist`, :ref:`needtable` or :ref:`needflow`. Which support additional options for related layout. +* Deprecated: ``needfilter`` is replaced by :ref:`needlist`, :ref:`needtable` or :ref:`needflow`. Which support additional options for related layout. * Improvement: Added :ref:`needtable` directive. * Improvement: Added `DataTables `_ support for :ref:`needtable` (including table search, excel/pdf export and dynamic column selection). * Improvement: Added :ref:`needs_id_regex`, which takes a regular expression and which is used to validate given IDs of needs. @@ -727,7 +727,7 @@ custom css definitions you need to update them. 0.1.37 ------ -* Bugfix: Implemented 0.1.36 bugfix also for :ref:`needfilter` and :ref:`needimport`. +* Bugfix: Implemented 0.1.36 bugfix also for ``needfilter`` and :ref:`needimport`. 0.1.36 ------ @@ -831,7 +831,7 @@ custom css definitions you need to update them. * Added configuration parameter :ref:`needs_id_required`. * Backwards compatibility changes: -* Reimplemented **needlist** as alias for :ref:`needfilter` +* Reimplemented **needlist** as alias for ``needfilter`` * Added *need* directive/need as part of the default :ref:`needs_types` configuration. 0.1.18 diff --git a/docs/conf.py b/docs/conf.py index 82fcd6a36..d9f6c17d4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -97,11 +97,8 @@ .. rst-class:: need .. rst-class:: need_{{type_name}} -.. container:: need - - .. container:: toggle - - .. container:: header +.. dropdown:: + :class: need :needs_type:`{{type_name}}`: {% if title %}:needs_title:`{{title}}`{% endif %} :needs_id:`{{id}}` @@ -457,9 +454,9 @@ def custom_defined_func(): html_favicon = "./_static/sphinx-needs-logo-favicon.png" # material theme options (see theme.conf for more information) html_theme_options = { - # "icon": { - # "repo": "fontawesome/brands/github-square", - # }, + "icon": { + "repo": "fontawesome/brands/github", + }, "site_url": "https://sphinxcontrib-needs.readthedocs.io/", "repo_url": "https://github.com/useblocks/sphinxcontrib-needs", "repo_name": "Sphinx-Needs", diff --git a/docs/configuration.rst b/docs/configuration.rst index 47bc9ceaf..adb9461b1 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -170,11 +170,7 @@ By using :ref:`needs_hide_options` the output of such options can be hidden. must use the :ref:`filter` option. -.. container:: toggle - - .. container:: header - - **Show example** +.. dropdown:: Show example **conf.py** @@ -633,11 +629,8 @@ If you do not set ``needs_report_template``, the default template used is: {# Output for needs_types #} {% if types|length != 0 %} - .. container:: toggle needs_report_table - - .. container:: header - - **Need Types** + .. dropdown:: Need Types + :class: needs_report_table .. list-table:: :widths: 40 20 20 20 @@ -658,11 +651,8 @@ If you do not set ``needs_report_template``, the default template used is: {# Output for needs_extra_links #} {% if links|length != 0 %} - .. container:: toggle needs_report_table - - .. container:: header - - **Need Extra Links** + .. dropdown:: Need Extra Links + :class: needs_report_table .. list-table:: :widths: 10 30 30 5 20 @@ -685,11 +675,8 @@ If you do not set ``needs_report_template``, the default template used is: {# Output for needs_options #} {% if options|length != 0 %} - .. container:: toggle needs_report_table - - .. container:: header - - **Need Extra Options** + .. dropdown:: Need Extra Options + :class: needs_report_table {% for option in options %} * {{ option }} @@ -699,11 +686,7 @@ If you do not set ``needs_report_template``, the default template used is: {# Output for needs metrics #} {% if usage|length != 0 %} - .. container:: toggle - - .. container:: header - - **Need Metrics** + .. dropdown:: Need Metrics .. list-table:: :widths: 40 40 @@ -2204,7 +2187,8 @@ If nothing is set, the following default template is used: .. rst-class:: need .. rst-class:: need_{{type_name}} - .. container:: need + .. dropdown:: + :class: need :needs_type:`{{type_name}}`: :needs_title:`{{title}}` :needs_id:`{{id}}` {%- if status and status|upper != "NONE" and not hide_status %} @@ -2265,11 +2249,8 @@ Default value: .. rst-class:: need .. rst-class:: need_{{type_name}} - .. container:: need - - .. container:: toggle - - .. container:: header + .. dropdown:: + :class: need :needs_type:`{{type_name}}`: :needs_title:`{{title}}` :needs_id:`{{id}}` :needs_type:`{{type_name}}`: :needs_title:`{{title}}` :needs_id:`{{id}}` diff --git a/docs/directives/needgantt.rst b/docs/directives/needgantt.rst index 6dec5478c..38a817a04 100644 --- a/docs/directives/needgantt.rst +++ b/docs/directives/needgantt.rst @@ -21,11 +21,7 @@ needgantt :tags: gantt_example :milestone_filter: type == 'milestone' -.. container:: toggle - - .. container:: header - - **Show used needs for above example** +.. dropdown:: Show used needs for above example .. action:: Find & Report bug :id: ACT_BUG @@ -139,11 +135,7 @@ Default: None :tags: gantt_ex_starts_with :starts_with_links: starts_with -.. container:: toggle - - .. container:: header - - **Show the needs used in the above example** +.. dropdown:: Show used needs for above example .. action:: Create example :id: ACT_CREATE_EX_SW @@ -185,11 +177,7 @@ Default: links :tags: gantt_ex_starts_after :starts_after_links: starts_after -.. container:: toggle - - .. container:: header - - **Show the needs used in the above example** +.. dropdown:: Show the needs used in the above example .. action:: Create example :id: ACT_CREATE_EX_SA @@ -225,11 +213,7 @@ Default: None :tags: gantt_ex_ends_with :ends_with_links: ends_with -.. container:: toggle - - .. container:: header - - **Show the needs used in the above example** +.. dropdown:: Show the needs used in the above example .. action:: Create example :id: ACT_CREATE_EX_EW @@ -339,11 +323,7 @@ Default: :ref:`need_duration` :tags: gantt_ex_duration :duration_option: hours -.. container:: toggle - - .. container:: header - - **Show the needs used in the above example** +.. dropdown:: Show the needs used in the above example .. action:: Create example :id: ACT_CREATE_EX @@ -387,11 +367,7 @@ Default: :ref:`need_completion` :tags: gantt_ex_completion :completion_option: amount -.. container:: toggle - - .. container:: header - - **Show the needs used in the above example** +.. dropdown:: Show the needs used in the above example .. action:: Create example :id: ACT_CREATE_EX_C diff --git a/docs/directives/needimport.rst b/docs/directives/needimport.rst index 881b520dd..0d367b207 100644 --- a/docs/directives/needimport.rst +++ b/docs/directives/needimport.rst @@ -74,7 +74,7 @@ hide ~~~~ You can use the ``:hide:`` option to set the **hide** tag for all imported needs. -So they do not show up but are available in :ref:`needfilter`. +So they do not show up but are available in ``needfilter``. collapse ~~~~~~~~ diff --git a/docs/directives/needlist.rst b/docs/directives/needlist.rst index 6837348aa..08e45ebda 100644 --- a/docs/directives/needlist.rst +++ b/docs/directives/needlist.rst @@ -36,11 +36,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. -.. container:: toggle - - .. container:: header - - **Show example** +.. dropdown:: Show example |ex| @@ -64,11 +60,7 @@ 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. -.. container:: toggle - - .. container:: header - - **Show example** +.. dropdown:: Show example |ex| @@ -92,11 +84,7 @@ show_filters If set, we add the used filter below the needlist results: -.. container:: toggle - - .. container:: header - - **Show example** +.. dropdown:: Show example |ex| diff --git a/docs/directives/needsequence.rst b/docs/directives/needsequence.rst index 4e9d81fa4..9b42c6aa0 100644 --- a/docs/directives/needsequence.rst +++ b/docs/directives/needsequence.rst @@ -21,61 +21,57 @@ needsequence :start: USER_A, USER_D :link_types: links, triggers -.. container:: toggle - - .. container:: header - - Show used needs for above example... - - .. user:: Mr. A - :id: USER_A - :links: ACT_ISSUE - :style: blue_border - - .. action:: Creates issue - :id: ACT_ISSUE - :links: USER_B - :style: yellow_border - - .. user:: Ms. B - :id: USER_B - :links: ACT_ANALYSIS, ACT_SOLUTION - :style: blue_border - - .. action:: Analysis issue - :id: ACT_ANALYSIS - :links: USER_B - :style: yellow_border - - .. action:: Provides solution - :id: ACT_SOLUTION - :links: USER_C - :style: yellow_border - - .. user:: Expert C - :id: USER_C - :links: ACT_REVIEW, ACT_INFORM - :style: blue_border - - .. action:: Reviews solution - :id: ACT_REVIEW - :links: USER_C - :style: yellow_border - - .. action:: Informs reporter - :id: ACT_INFORM - :links: USER_A - :style: yellow_border - - .. user:: Office Dog - :id: USER_D - :triggers: ACT_BARKS - :style: blue_border - - .. action:: Barks for support - :id: ACT_BARKS - :triggers: USER_D - :style: yellow_border +.. dropdown:: Show the needs used in the above example + + .. user:: Mr. A + :id: USER_A + :links: ACT_ISSUE + :style: blue_border + + .. action:: Creates issue + :id: ACT_ISSUE + :links: USER_B + :style: yellow_border + + .. user:: Ms. B + :id: USER_B + :links: ACT_ANALYSIS, ACT_SOLUTION + :style: blue_border + + .. action:: Analysis issue + :id: ACT_ANALYSIS + :links: USER_B + :style: yellow_border + + .. action:: Provides solution + :id: ACT_SOLUTION + :links: USER_C + :style: yellow_border + + .. user:: Expert C + :id: USER_C + :links: ACT_REVIEW, ACT_INFORM + :style: blue_border + + .. action:: Reviews solution + :id: ACT_REVIEW + :links: USER_C + :style: yellow_border + + .. action:: Informs reporter + :id: ACT_INFORM + :links: USER_A + :style: yellow_border + + .. user:: Office Dog + :id: USER_D + :triggers: ACT_BARKS + :style: blue_border + + .. action:: Barks for support + :id: ACT_BARKS + :triggers: USER_D + :style: yellow_border Sequence diagrams supports special needs-combinations, in which one type represents some kind of a ``participant`` and another, linked need is representing the ``message``. |br| @@ -124,8 +120,6 @@ The above, linked example gets interpreted for ``needsequence`` as follows: p1 -> p2: Message 1 p2 -> p3: Message 2 - - @enduml diff --git a/docs/directives/needtable.rst b/docs/directives/needtable.rst index de2957d20..8e26f9f11 100644 --- a/docs/directives/needtable.rst +++ b/docs/directives/needtable.rst @@ -45,11 +45,7 @@ For instance:: This will show the columns *id*, *title* and *tags* in the order given. -.. container:: toggle - - .. container:: header - - **Show example** +.. dropdown:: Show example |ex| @@ -123,11 +119,7 @@ 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. -.. container:: toggle - - .. container:: header - - **Show example** +.. dropdown:: Show example |ex| @@ -153,11 +145,7 @@ show_filters If set, we add the used filter above the table: -.. container:: toggle - - .. container:: header - - **Show example** +.. dropdown:: Show example |ex| @@ -191,11 +179,7 @@ Supported values are: Overrides config parameter :ref:`needs_table_style` if set. -.. container:: toggle - - .. container:: header - - **Show example** +.. dropdown:: Show example |ex| @@ -245,11 +229,7 @@ To change the prefix please read :ref:`needs_part_prefix`. -.. container:: toggle - - .. container:: header - - **Show above example's configuration** +.. dropdown:: Show above example's configuration .. code-block:: rst @@ -347,11 +327,7 @@ part of the row style. So a copied status value like ``in progress`` will become ``in_progress``. -.. container:: toggle - - .. container:: header - - **Show used configuration** +.. dropdown:: Show used configuration **needtable** @@ -432,11 +408,7 @@ In this case, we set the sort option to ``status``. So *EX_ROW_3* is above of *E :style: table :sort: status -.. container:: toggle - - .. container:: header - - **Show used configuration** +.. dropdown:: Show used configuration .. code-block:: rst diff --git a/docs/directives/needuml.rst b/docs/directives/needuml.rst index 5d3c45b68..e49f6c8f8 100644 --- a/docs/directives/needuml.rst +++ b/docs/directives/needuml.rst @@ -33,7 +33,7 @@ which allows you to use loops, if-clauses, and it injects data from need-objects :tags: needuml :status: draft - Secound example Need for NeedUml. + Second example Need for NeedUml. .. needuml:: @@ -62,7 +62,7 @@ which allows you to use loops, if-clauses, and it injects data from need-objects :tags: needuml :status: draft - Secound example Need for NeedUml. + Second example Need for NeedUml. .. needuml:: diff --git a/docs/examples/index.rst b/docs/examples/index.rst index 9fd04b0e6..2d4fff7cd 100644 --- a/docs/examples/index.rst +++ b/docs/examples/index.rst @@ -147,7 +147,9 @@ As :need:`IMPL_01` shows, the linked :need:`OWN_ID_123` is realisable. .. needflow:: :filter: "Referencing and filtering needs" == section_name -Used rst code:: +Used rst code: + +.. code-block:: rst .. req:: My first requirement :status: open diff --git a/docs/filter.rst b/docs/filter.rst index f43304f5d..6962cab7b 100644 --- a/docs/filter.rst +++ b/docs/filter.rst @@ -19,7 +19,7 @@ The following filter options are supported by directives: * :ref:`needtable` * :ref:`needflow` * :ref:`needpie` - * :ref:`needfilter` (deprecated!) + * ``needfilter`` (deprecated!) * :ref:`needextend` @@ -42,11 +42,7 @@ Use the **status** option to filter needs by their status. You can easily filter for multiple statuses by separating them by ";". Example: *open; in progress; reopen*. -.. container:: toggle - - .. container:: header - - **Show example** +.. dropdown:: Show example .. code-block:: rst @@ -67,11 +63,7 @@ tags To search for multiple tags, simply separate them by using ";". -.. container:: toggle - - .. container:: header - - **Show example** +.. dropdown:: Show example .. code-block:: rst @@ -90,11 +82,7 @@ types ~~~~~ For **:types:** the type itself or the human-readable type-title can be used as filter value. -.. container:: toggle - - .. container:: header - - **Show example** +.. dropdown:: Show example .. code-block:: rst @@ -112,11 +100,7 @@ sort_by ~~~~~~~ Sorts the result list. Allowed values are ``status`` or any alphanumerical property. -.. container:: toggle - - .. container:: header - - **Show example** +.. dropdown:: Show example .. code-block:: rst @@ -216,11 +200,7 @@ Additional variables for :ref:`need_part`: If your expression is valid and it's True, the related need is added to the filter result list. If it is invalid or returns False, the related need is not taken into account for the current filter. -.. container:: toggle - - .. container:: header - - **Show example** +.. dropdown:: Show example .. code-block:: rst @@ -286,11 +266,7 @@ search(pattern, variable) is based on The first parameter must be a regular expression pattern. The second parameter should be one of the above variables(status, id, content, ..) -.. container:: toggle - - .. container:: header - - **Show example** +.. dropdown:: Show example This example uses a regular expressions to find all needs with an e-mail address in title. diff --git a/docs/needs_templates/report_template.need b/docs/needs_templates/report_template.need index 2a6f9a42d..1f0d65d78 100644 --- a/docs/needs_templates/report_template.need +++ b/docs/needs_templates/report_template.need @@ -1,10 +1,7 @@ {# Output for needs_types #} {% if types|length != 0 %} -.. container:: toggle - .. container:: header - - **Need Types** +.. dropdown:: Need Types {% for type in types %} * {{ type.title | upper }} @@ -17,11 +14,8 @@ {# Output for needs_options #} {% if options|length != 0 %} -.. container:: toggle - - .. container:: header - **Need Extra Options** +.. dropdown:: Need Extra Options {% for option in options %} * {{ option }} @@ -31,11 +25,8 @@ {# Output for needs_extra_links #} {% if links|length != 0 %} -.. container:: toggle - - .. container:: header - **Need Extra Links** +.. dropdown:: Need Extra Links {% for link in links %} * {{ link.option | upper }} diff --git a/docs/services/open_needs.rst b/docs/services/open_needs.rst index 5b9ca9eb6..55663ce61 100644 --- a/docs/services/open_needs.rst +++ b/docs/services/open_needs.rst @@ -96,11 +96,7 @@ or a list/tuple, which defines the location of the value in the retrieved servic .. _open_need_data: -.. container:: toggle - - .. container:: header - - **Example of an Open-Needs service data object** +.. dropdown:: Example of an Open-Needs service data object .. code-block:: diff --git a/sphinx_needs/directives/needreport_template.rst b/sphinx_needs/directives/needreport_template.rst index 424544f46..2b34eccfc 100644 --- a/sphinx_needs/directives/needreport_template.rst +++ b/sphinx_needs/directives/needreport_template.rst @@ -1,10 +1,7 @@ {# Output for needs_types #} {% if types|length != 0 %} -.. container:: toggle - .. container:: header - - **Need Types** +.. dropdown:: Need Types .. list-table:: :widths: 40 20 20 20 @@ -25,11 +22,8 @@ {# Output for needs_extra_links #} {% if links|length != 0 %} -.. container:: toggle - - .. container:: header - **Need Extra Links** +.. dropdown:: Need Extra Links .. list-table:: :widths: 10 30 30 5 20 @@ -52,11 +46,8 @@ {# Output for needs_options #} {% if options|length != 0 %} -.. container:: toggle - .. container:: header - - **Need Extra Options** +.. dropdown:: Need Extra Options {% for option in options %} * {{ option }} @@ -66,11 +57,8 @@ {# Output for needs metrics #} {% if usage|length != 0 %} -.. container:: toggle - - .. container:: header - **Need Metrics** +.. dropdown:: Need Metrics .. list-table:: :widths: 40 40 diff --git a/sphinx_needs/layout.py b/sphinx_needs/layout.py index 38a8fb36e..869801cbb 100644 --- a/sphinx_needs/layout.py +++ b/sphinx_needs/layout.py @@ -702,7 +702,15 @@ def meta_links_all(self, prefix: str = "", postfix: str = "", exclude=None): return data_container def image( - self, url, height=None, width=None, align=None, no_link=False, prefix: str = "", is_external: bool = False + self, + url, + height=None, + width=None, + align=None, + no_link=False, + prefix: str = "", + is_external: bool = False, + img_class: str = "", ) -> nodes.inline: """ See https://docutils.sourceforge.io/docs/ref/rst/directives.html#images @@ -727,6 +735,7 @@ def image( :param no_link: :param prefix: Prefix string in front of the image :param is_external: If ``True`` url references an external image, which needs to be downloaded + :param img_class: Custom class name for image element :return: An inline docutils node element :rtype: :class: docutils.nodes.inline """ @@ -808,10 +817,15 @@ def image( url = file_path - if no_link: - classes = ["needs_image", "no-scaled-link"] - else: - classes = ["needs_image"] + classes = [] + if len(img_class) != 0 and no_link: + classes.extend([img_class, "no-scaled-link"]) + + if len(img_class) == 0 and no_link: + classes.extend(["needs_image", "no-scaled-link"]) + + if len(img_class) == 0 and not no_link: + classes.append("needs_image") image_node = nodes.image(url, classes=classes, **options) image_node["candidates"] = {"*": url} @@ -905,14 +919,18 @@ def collapse_button( coll_node_visible = nodes.inline(classes=["needs", "visible"]) if collapsed.startswith("image:") or collapsed.startswith("icon:"): - coll_node_collapsed.append(self.image(collapsed.replace("image:", ""), width="17px", no_link=True)) + coll_node_collapsed.append( + self.image(collapsed.replace("image:", ""), width="17px", no_link=True, img_class="sn_collapse_img") + ) elif collapsed.startswith("Debug view"): coll_node_collapsed.append(nodes.container(classes=["debug_on_layout_btn"])) # For debug layout else: coll_node_collapsed.append(nodes.Text(collapsed)) if visible.startswith("image:") or visible.startswith("icon:"): - coll_node_visible.append(self.image(visible.replace("image:", ""), width="17px", no_link=True)) + coll_node_visible.append( + self.image(visible.replace("image:", ""), width="17px", no_link=True, img_class="sn_collapse_img") + ) elif visible.startswith("Debug view"): coll_node_visible.append(nodes.container(classes=["debug_off_layout_btn"])) else: