diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index a97d38197..513b122b3 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -28,6 +28,8 @@ jobs: run: ubc check docs - name: Run 'ubc build index docs' run: ubc build index docs --show-warnings + - name: Run 'ubc format docs' + run: ubc format docs --preview --check tests-core: name: "Core py${{ matrix.python-version }} sphinx~=${{ matrix.sphinx-version }} ${{ matrix.os }}" diff --git a/docs/api.rst b/docs/api.rst index b0de136aa..417a012d6 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -27,7 +27,6 @@ Need .. automodule:: sphinx_needs.api.need :members: - Exceptions ---------- diff --git a/docs/builders.rst b/docs/builders.rst index e869e1820..70dece935 100644 --- a/docs/builders.rst +++ b/docs/builders.rst @@ -3,10 +3,11 @@ Builders ======== -.. _needs_builder: +.. _`needs_builder`: needs ----- + .. versionadded:: 0.1.30 The **needs** builder exports all found needs and selected filter results to a single json file. @@ -18,8 +19,7 @@ Usage .. code-block:: bash - sphinx-build -b needs source_dir build_dir - + sphinx-build -b needs source_dir build_dir .. hint:: @@ -35,10 +35,11 @@ If a **needs.json** is imported (see :ref:`needs_file`) and you raise the docume version(s) inside the **needs.json**. .. hint:: + If you generate and store/archive (e.g. in git) the **needs.json** file every time you raise your documentation version, you will get a nice history data. -.. _needs_builder_format: +.. _`needs_builder_format`: Format ++++++ @@ -54,106 +55,106 @@ See also :ref:`needs_json_exclude_fields`, :ref:`needs_json_remove_defaults`, an .. code-block:: python - { - "created": "2017-07-03T11:54:42.433876", - "current_version": "1.5", - "project": "needs test docs", - "versions": { - "1.0": { - "created": "2017-07-03T11:54:42.433868", - "needs_schema": { - "$schema": "http://json-schema.org/draft-07/schema#", - "properties": { - "id": { - "description": "ID of the data.", - "field_type": "core", - "type": "string" - }, - "type": { - "description": "Type of the need.", - "field_type": "core", - "type": "string" - }, - "links": { - "description": "Link field", - "field_type": "links", - "items": { - "type": "string" - }, - "type": "array", - "default": [] - }, - "status": { - "description": "Status of the need.", - "field_type": "core", - "type": [ - "string", - "null" - ], - "default": null - }, - ... - } - }, - "needs_defaults_removed": true, - "needs": { - "IMPL_01": { - "id": "IMPL_01", - "type": "impl", - "links": ["OWN_ID_123"], - ... - }, - ... - } - }, - "1.5": { - "created": "2017-07-03T16:10:31.633425", - "needs_schema": { - "id": { - "description": "ID of the data.", - "field_type": "core", - "type": "string" - }, - "type": { - "description": "Type of the need.", - "field_type": "core", - "type": "string" - }, - "links": { - "description": "Link field", - "field_type": "links", - "items": { - "type": "string" - }, - "type": "array", - "default": [] - }, - "status": { - "description": "Status of the need.", - "field_type": "core", - "type": [ - "string", - "null" - ], - "default": null - }, - ... - }, - "needs_defaults_removed": true, - "needs": { - "IMPL_01": { - "id": "IMPL_01", - "type": "impl", - "links": ["OWN_ID_123"], - "status": "closed", - ... - }, - ... - } - } - } - -.. _needumls_builder: + { + "created": "2017-07-03T11:54:42.433876", + "current_version": "1.5", + "project": "needs test docs", + "versions": { + "1.0": { + "created": "2017-07-03T11:54:42.433868", + "needs_schema": { + "$schema": "http://json-schema.org/draft-07/schema#", + "properties": { + "id": { + "description": "ID of the data.", + "field_type": "core", + "type": "string" + }, + "type": { + "description": "Type of the need.", + "field_type": "core", + "type": "string" + }, + "links": { + "description": "Link field", + "field_type": "links", + "items": { + "type": "string" + }, + "type": "array", + "default": [] + }, + "status": { + "description": "Status of the need.", + "field_type": "core", + "type": [ + "string", + "null" + ], + "default": null + }, + ... + } + }, + "needs_defaults_removed": true, + "needs": { + "IMPL_01": { + "id": "IMPL_01", + "type": "impl", + "links": ["OWN_ID_123"], + ... + }, + ... + } + }, + "1.5": { + "created": "2017-07-03T16:10:31.633425", + "needs_schema": { + "id": { + "description": "ID of the data.", + "field_type": "core", + "type": "string" + }, + "type": { + "description": "Type of the need.", + "field_type": "core", + "type": "string" + }, + "links": { + "description": "Link field", + "field_type": "links", + "items": { + "type": "string" + }, + "type": "array", + "default": [] + }, + "status": { + "description": "Status of the need.", + "field_type": "core", + "type": [ + "string", + "null" + ], + "default": null + }, + ... + }, + "needs_defaults_removed": true, + "needs": { + "IMPL_01": { + "id": "IMPL_01", + "type": "impl", + "links": ["OWN_ID_123"], + "status": "closed", + ... + }, + ... + } + } + } + +.. _`needumls_builder`: needumls -------- @@ -168,23 +169,21 @@ Usage .. code-block:: bash - make needumls + make needumls or .. code-block:: bash - sphinx-build -M needumls source_dir build_dir + sphinx-build -M needumls source_dir build_dir -.. hint:: +.. hint:: As an alternative, you can set the config option :ref:`needs_build_needumls` to export the needumls files during each build. - As an alternative, you can set the config option :ref:`needs_build_needumls` to export the needumls files during each build. - - -.. _needs_id_builder: +.. _`needs_id_builder`: needs_id -------- + .. versionadded:: 2.0.0 The **needs_id** builder exports all found needs and selected filter results to a set json files of each need with the name is ``id`` of need. @@ -196,4 +195,4 @@ Usage .. code-block:: bash - sphinx-build -b needs_id source_dir build_dir + sphinx-build -b needs_id source_dir build_dir diff --git a/docs/changelog.rst b/docs/changelog.rst index e5216e3a4..ad20b7867 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -1,5 +1,4 @@ -.. _ubCode: https://ubcode.useblocks.com/ - +.. _ubcode: https://ubcode.useblocks.com/ .. _changelog: Changelog @@ -336,8 +335,8 @@ but may be in some corner cases. .. code-block:: rst - .. needextend:: c.this_doc() and status is None - :status: open + .. needextend:: c.this_doc() and status is None + :status: open This works for all common filtered directives, see :ref:`filter_current_page` @@ -490,7 +489,7 @@ This change has required changes to the internal API and stricter control on the Additionally, to identify any long running filters, the :ref:`needs_uml_process_max_time`, :ref:`needs_filter_max_time` and :ref:`needs_debug_filters` configuration options have been added. -Key changes were made in: +Key changes were made in: - ♻️ Replace need dicts/lists with views (with fast filtering) in :pr:`1281` - πŸ”§ split ``filter_needs`` func by needs type in :pr:`1276` @@ -583,7 +582,7 @@ Updated dependencies - sphinx-data-viewer: ``^0.1.1`` to ``^0.1.5`` Documentation and CSS styling -.............................. +............................. The documentation theme has been completely updated, and a tutorial added. @@ -595,7 +594,7 @@ See :ref:`install_theme` for more information on how to setup CSS for different and :pr:`1178`, :pr:`1181`, :pr:`1182` and :pr:`1184` for the changes. ``needflow`` improvements -.......................... +......................... The use of `Graphviz `__ as the underlying engine for ``needflow`` diagrams, in addition to the default `PlantUML `__, is now allowed via the global :ref:`needs_flow_engine` configuration option, or the per-diagram :ref:`engine ` option. @@ -612,7 +611,7 @@ additional improvements: - ✨ Add ``border_color`` option for ``needflow`` in :pr:`1194` ``needs.json`` improvements -............................ +........................... A ``needs_schema`` is now included in the ``needs.json`` file (per version), which is a JSON schema for the data structure of a single need. @@ -636,7 +635,6 @@ Additional improvements - πŸ‘Œ Allow ``collapse`` / ``delete`` / ``jinja_content`` directive options to be flags in :pr:`1188` - πŸ‘Œ Improve ``need-extend``; allow dynamic functions in lists in :pr:`1076` - πŸ‘Œ Add collapse button to ``clean_xxx`` layouts in :pr:`1187` - - πŸ› fix warnings for duplicate needs in parallel builds in :pr:`1223` - πŸ› Fix rendering of ``needextract`` needs and use warnings instead of exceptions in :pr:`1243` and :pr:`1249` @@ -670,11 +668,10 @@ Bug fixes - πŸ› Centralise need missing link reporting in :pr:`1104` Internal improvements -...................... +..................... - πŸ”§ Use future annotations in all modules in :pr:`1111` - πŸ”§ Replace black/isort/pyupgrade/flake8 with ruff in :pr:`1080` - - πŸ”§ Add better typing for ``extra_links`` config variable in :pr:`1131` - πŸ”§ Centralise need parts creation and strongly type needs in :pr:`1129` - πŸ”§ Fix typing of need docname/lineno in :pr:`1134` @@ -682,7 +679,6 @@ Internal improvements - πŸ”§ Enforce type checking in ``needuml.py`` in :pr:`1116` - πŸ”§ Enforce type checking in ``api/need.py`` in :pr:`1117` - πŸ”§ Add better typing for ``global_options`` config variable in :pr:`1120` - - πŸ”§ Move dead link need fields to internals in :pr:`1119` - πŸ”§ Remove usage of ``hide_status`` and ``hide_tags`` in :pr:`1130` - πŸ”§ Remove ``hidden`` field from ``extra_options`` in :pr:`1124` @@ -697,7 +693,7 @@ Internal improvements :Released: 13.11.2023 :Full Changelog: `1.3.0...v2.0.0 `__ -This release is focussed on improving the internal code-base and its build time performance, as well as improved build warnings and other functionality improvements / fixes. +This release is focussed on improving the internal code-base and its build time performance, as well as improved build warnings and other functionality improvements / fixes. Changed ....... @@ -717,7 +713,7 @@ New Improved ........ -Performance: +Performance: * General performance improvement (up to 50%) and less memory consumption (~40%). * ``external_needs`` now uses cached templates to save generation time. @@ -759,13 +755,11 @@ Internal * πŸ”§ Remove ``unwrap`` function (:pr:`1017`) * πŸ”§ Add ``remove_node_from_tree`` utility function (:pr:`1063`) * ♻️ Refactor needs post-processing function signatures (:pr:`1040`) - * πŸ“š Simplify Sphinx-Needs docs builds (:pr:`972`) * πŸ“š Always use headless plantuml (:pr:`983`) * πŸ“š Add intersphinx (:pr:`991`) * πŸ“š Add outline of extension logic (:pr:`1012`) * πŸ“š Fixed extra links example (:pr:`1016`) - * πŸ§ͺ Remove boilerplate from test build ``conf.py`` files (:pr:`989`, :pr:`990`) * πŸ§ͺ Add headless java to test builds (:pr:`988`) * πŸ§ͺ Add snapshot testing (:pr:`1019`, :pr:`1020`, :pr:`1059`) @@ -777,6 +771,7 @@ Internal 1.3.0 ----- + Released: 16.08.2023 * Improvement: Configuration option :ref:`needs_debug_measurement` added, which creates a runtime report @@ -804,6 +799,7 @@ Released: 16.08.2023 1.2.2 ----- + Released: 08.02.2023 * Bugfix: Changed needed version of jsonschema-lib to be not so strict. @@ -813,6 +809,7 @@ Released: 08.02.2023 1.2.1 ----- + Released: 08.02.2023 * Bugfix: Fixed pygls version compatibility. @@ -823,6 +820,7 @@ Released: 08.02.2023 1.2.0 ----- + Released: 24.01.2023 * Bugfix: Allowing newer versions of jsonschema. @@ -834,6 +832,7 @@ Released: 24.01.2023 1.1.1 ----- + Released: 21.12.2022 * Bugfix: Removed outdated JS codes that handles the collapse button. @@ -855,6 +854,7 @@ Released: 21.12.2022 1.1.0 ----- + Released: 22.11.2022 * Bugfix: Expand/Collapse button does not work. @@ -874,8 +874,8 @@ Released: 22.11.2022 1.0.3 ----- -Released: 08.11.2022 +Released: 08.11.2022 * Improvement: Fixed :ref:`needextend` error handling by adding a strict-mode option to it. (:issue:`747`) @@ -926,8 +926,8 @@ Released: 08.11.2022 1.0.2 ----- -Released: 22.09.2022 +Released: 22.09.2022 * Improvement: Added support for variants handling for need options. (:issue:`671`) @@ -962,6 +962,7 @@ Released: 22.09.2022 1.0.1 ----- + Released: 11.07.2022 * Notice: **Sphinx <5.0 is no longer supported.** @@ -992,6 +993,7 @@ Released: 11.07.2022 0.7.9 ----- + Released: 10.05.2022 * Improvement: Add permanent link layout function. @@ -1005,6 +1007,7 @@ Released: 10.05.2022 0.7.8 ----- + Released: 29.03.2022 * Improvement: Provides line number info for needs node. @@ -1021,6 +1024,7 @@ Released: 29.03.2022 0.7.7 ----- + Released: 04.03.2022 * Bugfix: ``need`` role supporting lower and upper IDs. @@ -1034,6 +1038,7 @@ Released: 04.03.2022 0.7.6 ----- + Released: 28.02.2022 * Improvement: :ref:`filter_func` support arguments. @@ -1051,6 +1056,7 @@ Released: 28.02.2022 0.7.5 ----- + Released: 21.01.2022 * Improvement: :ref:`needbar` is introduced @@ -1077,6 +1083,7 @@ Released: 21.01.2022 0.7.4 ----- + Released: 30.11.2021 * Improvement: Adds :ref:`needservice_debug` flag for :ref:`needservice`. @@ -1092,6 +1099,7 @@ Released: 30.11.2021 0.7.3 ----- + Released: 08.11.2021 * Improvement: Schema check for ``need.json`` files implemented. @@ -1110,6 +1118,7 @@ Released: 08.11.2021 0.7.2 ----- + Released: 08.10.2021 * Improvement: New config option :ref:`needs_builder_filter` to define a filter for the needs builder. @@ -1144,6 +1153,7 @@ Released: 08.10.2021 0.7.1 ----- + Released: 21.07.2021 * Improvement: Support for parallel sphinx-build when using ``-j`` option @@ -1157,6 +1167,7 @@ Released: 21.07.2021 0.7.0 ----- + Released: 06.07.2021 * Improvement: Providing :ref:`needs_external_needs` to allow usage and referencing of external needs. @@ -1178,6 +1189,7 @@ Released: 06.07.2021 0.6.3 ----- + Released: 18.06.2021 * Improvement: Dead links (references to not found needs) are supported and configurable by :ref:`allow_dead_links`. @@ -1206,6 +1218,7 @@ Released: 18.06.2021 0.6.2 ----- + Released: 30.04.2021 * Improvement: Parent needs of nested needs get collected and are available in filters. @@ -1219,6 +1232,7 @@ Released: 30.04.2021 0.6.1 ----- + Released: 23.04.2021 * Support: Removes support for Sphinx version <3.0 (Sphinx 2.x may still work, but it gets not tested). @@ -1265,6 +1279,7 @@ Released: 23.04.2021 0.5.5 ----- + * Improvement: Added :ref:`needsequence` directive. (:issue:`144`) * Improvement: Added :ref:`needgantt` directive. (:issue:`146`) * Improvement: Added two new need-options: :ref:`need_duration` and :ref:`need_completion` @@ -1277,6 +1292,7 @@ Released: 23.04.2021 0.5.4 ----- + * Improvement: Added options :ref:`need_pre_template` and :ref:`need_post_template` for needs. (:issue:`139`) * Bugfix: Setting correct default value for :ref:`needs_statuses` (:issue:`136`) * Bugfix: Dynamic functions can be used in links (text and url) now. @@ -1285,6 +1301,7 @@ Released: 23.04.2021 0.5.3 ----- + * Improvement: Added ``transparent`` for transparent background to needflow configurations. * Improvement: :ref:`needflow` uses directive argument as caption now. * Improvement: Added option :ref:`needflow_align` to align needflow images. @@ -1301,6 +1318,7 @@ Released: 23.04.2021 0.5.2 ----- + * Improvement: **Sphinx-Needs** configuration gets checked before build. (:issue:`118`) * Improvement: ``meta_links_all`` :ref:`layout function ` now supports an exclude parameter * Improvement: :ref:`needflow`'s :ref:`connection line and arrow type ` can be configured. @@ -1322,6 +1340,7 @@ Released: 23.04.2021 0.5.1 ----- + * Improvement: Added :ref:`needextract` directive to mirror existing needs for special outputs. (:issue:`66`) * Improvement: Added new styles ``discreet`` and ``discreet_border``. * Bugfix: Some minor css fixes for new layout system. @@ -1377,6 +1396,7 @@ custom css definitions you need to update them. 0.4.1 ----- + * Improvement: Added :ref:`need_style` option to allow custom styles for needs. * Improvement: Added :ref:`needtable_style_row` option to allow custom styles for table rows and columns. @@ -1384,6 +1404,7 @@ custom css definitions you need to update them. 0.4.0 ----- + * Improvement: Provides API for other sphinx-extensions. See :ref:`api` for documentation. * Improvement: Added :ref:`support` page. * Bugfix: Fixed deprecation warnings to support upcoming Sphinx3.0 API. @@ -1392,6 +1413,7 @@ custom css definitions you need to update them. 0.3.15 ------ + * Improvement: In filter operations, all needs can be accessed by using keyword ``needs``. * Bugfix: Removed prefix from normal needs for needtable (:issue:`97`) @@ -1399,6 +1421,7 @@ custom css definitions you need to update them. 0.3.14 ------ + * Improvement: Added config option :ref:`needs_role_need_max_title_length` to define the maximum title length of referenced needs. (:issue:`95`) @@ -1406,6 +1429,7 @@ custom css definitions you need to update them. 0.3.13 ------ + * Bugfix: Filters on needs with ``id_parent`` or ``id_complete`` do not raise an exception any more and filters gets executed correctly. @@ -1413,6 +1437,7 @@ custom css definitions you need to update them. 0.3.12 ------ + * Improvement: Tables can be sorted by any alphanumeric option. (:issue:`92`) * Improvement: :ref:`need_part` are now embedded in their parent need, if :ref:`needflow` is used. (:issue:`83`) * Bugfix: Links to :ref:`need_part` are no longer rendered to parent need, instead the link goes directly to the need_part. (:issue:`91`) @@ -1422,6 +1447,7 @@ custom css definitions you need to update them. 0.3.11 ------ + * Improvement: Added config option :ref:`needs_extra_links` to define additional link types like *blocks*, *tested by* and more. Supports also style configuration and custom presentation names for links. * Improvement: Added :ref:`!export_id` option for filter directives to export results of filters to ``needs.json``. @@ -1433,6 +1459,7 @@ custom css definitions you need to update them. 0.3.10 ------ + * Bugfix: **type** was missing in output of builder :ref:`needs_builder` (:issue:`79`) * Bugfix: **needs_functions** parameter in *conf.py* created a sphinx error, if containing python methods. Internal workaround added, so that usage of own @@ -1442,6 +1469,7 @@ custom css definitions you need to update them. 0.3.9 ----- + * Bugfix: Grubby tag/link strings in needs, which define empty links/tags, produce a warning now. * Bugfix: Better logging of document location, if a filter string is not valid. * Bugfix: Replaced all print-statements with sphinx warnings. @@ -1459,6 +1487,7 @@ custom css definitions you need to update them. 0.3.7 ----- + * Improvement: :ref:`filter_string` now supports the filtering of :ref:`need_part`. * Improvement: The ID of a need is now printed as link, which can easily be used for sharing. (:issue:`75`) * Bugfix: Filter functionality in different directives are now using the same internal filter function. @@ -1468,6 +1497,7 @@ custom css definitions you need to update them. 0.3.6 ----- + * Improvement: Added needtable option :ref:`needtable_show_parts`. * Improvement: Added configuration option :ref:`needs_part_prefix`. * Improvement: Added docname to output file of builder :ref:`needs_builder` @@ -1477,6 +1507,7 @@ custom css definitions you need to update them. 0.3.5 ----- + * Bugfix: A :ref:`need_part` without a given ID gets a random id based on its content now. * Bugfix: Calculation of outgoing links does not crash, if need_parts are involved. @@ -1484,35 +1515,40 @@ custom css definitions you need to update them. 0.3.4 ----- + * Bugfix: Need representation in PDFs were broken (e.g. all meta data on one line). .. _`release:0.3.3`: 0.3.3 ----- + * Bugfix: Latex and Latexpdf are working again. .. _`release:0.3.2`: 0.3.2 ----- + * Bugfix: Links to parts of needs (:ref:`need_part`) are now stored and presented as *links incoming* of target link. .. _`release:0.3.1`: 0.3.1 ----- + * Improvement: Added dynamic function :ref:`check_linked_values`. * Improvement: Added dynamic function :ref:`calc_sum`. * Improvement: Added role :ref:`need_count`, which shows the amount of found needs for a given filter-string. * Bugfix: Links to :ref:`need_part` in :ref:`needflow` are now shown correctly as extra line between - need_parts containing needs. + need_parts containing needs. * Bugfix: Links to :ref:`need_part` in :ref:`needtable` are now shown and linked correctly in tables. .. _`release:0.3.0`: 0.3.0 ----- + * Improvement: :ref:`dynamic_functions` are now available to support calculation of need values. * Improvement: :ref:`needs_functions` can be used to register and use own dynamic functions. * Improvement: Added :ref:`needs_global_options` to set need values globally for all needs. @@ -1524,18 +1560,21 @@ custom css definitions you need to update them. 0.2.5 ----- + * Bugfix: Fix for changes made in 0.2.5. .. _`release:0.2.4`: 0.2.4 ----- + * Bugfix: Fixed performance issue (:issue:`63`) .. _`release:0.2.3`: 0.2.3 ----- + * Improvement: Titles can now be made optional. See :ref:`needs_title_optional`. (:issue:`49`) * Improvement: Titles be auto-generated from the first sentence of a requirement. See :ref:`needs_title_from_content` and :ref:`title_from_content`. (:issue:`49`) * Improvement: Titles can have a maximum length. See :ref:`needs_max_title_length`. (:issue:`49`) @@ -1544,6 +1583,7 @@ custom css definitions you need to update them. 0.2.2 ----- + * Improvement: The sections, to which a need belongs, are now stored, filterable and exported in ``needs.json``. See updated :ref:`option_filter`. (:pr:`53` ) * Improvement: Project specific options for needs are supported now. See :ref:`needs_extra_options`. (:pr:`48` ) * Bugfix: Logging fixed (:issue:`50` ) @@ -1553,6 +1593,7 @@ custom css definitions you need to update them. 0.2.1 ----- + * Bugfix: Sphinx warnings fixed, if need-collapse was used. (:issue:`46`) * Bugfix: dark.css, blank.css and common.css used wrong need-container selector. Fixed. @@ -1560,6 +1601,7 @@ custom css definitions you need to update them. 0.2.0 ----- + * 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). @@ -1575,6 +1617,7 @@ custom css definitions you need to update them. 0.1.49 ------ + * Bugfix: Supporting plantuml >= 0.9 (:issue:`38`) * Bugfix: need_outgoing does not crash, if given need-id does not exist (:issue:`32`) @@ -1582,15 +1625,17 @@ custom css definitions you need to update them. 0.1.48 ------ + * Improvement: Added configuration option :ref:`needs_role_need_template`. * Bugfix: Referencing not existing needs will result in build warnings instead of a build crash. * Refactoring: needs development files are stored internally under *sphinxcontrib/needs*, which is in sync with - most other sphinxcontrib-packages. + most other sphinxcontrib-packages. .. _`release:0.1.47`: 0.1.47 ------ + * Bugfix: dark.css was missing in MANIFEST.in. * Improvement: Better output, if configured needs_css file can not be found during build. @@ -1598,24 +1643,28 @@ custom css definitions you need to update them. 0.1.46 ------ + * Bugfix: Added python2/3 compatibility for needs_import. .. _`release:0.1.45`: 0.1.45 ------ + * Bugfix: needs with no status are handled the correct way now. .. _`release:0.1.44`: 0.1.44 ------ + * Bugfix: Import statements are checked, if Python 2 or 3 is used. .. _`release:0.1.43`: 0.1.43 ------ + * Improvement: Added "dark.css" as style * Bugfix: Removed "," as as separator of links in need presentation. @@ -1623,6 +1672,7 @@ custom css definitions you need to update them. 0.1.42 ------ + * Improvement: Added config parameter :ref:`needs_css`, which allows to set a css file. * Improvement: Most need-elements (title, id, tags, status, ...) got their own html class attribute to support custom styles. * Improvement: Set default style "modern.css" for all projects without configured :ref:`needs_css` parameter. @@ -1639,12 +1689,14 @@ custom css definitions you need to update them. 0.1.40 ------ + * Bugfix: Removed jinja activation .. _`release:0.1.39`: 0.1.39 ------ + * Bugfix: Added missing needimport_template.rst to package * Bugfix: Corrected version param of needimport @@ -1652,25 +1704,29 @@ custom css definitions you need to update them. 0.1.38 ------ + * Improvement: **:links:**, **:tags:** and other list-based options can handle "," as delimiter - (beside documented ";"). No spooky errors are thrown any more if "," is used accidentally. + (beside documented ";"). No spooky errors are thrown any more if "," is used accidentally. .. _`release:0.1.37`: 0.1.37 ------ + * Bugfix: Implemented 0.1.36 bugfix also for ``needfilter`` and :ref:`needimport`. .. _`release:0.1.36`: 0.1.36 ------ + * Bugfix: Empty **:links:** and **:tags:** options for :ref:`need` raise no error during build. .. _`release:0.1.35`: 0.1.35 ------ + * Improvement/Bug: Updated default node_template to use less space for node parameter representation * Improvement: Added **:filter:** option to :ref:`needimport` directive * Bugfix: Set correct default value for **need_list** option. So no more warnings should be thrown during build. @@ -1680,6 +1736,7 @@ custom css definitions you need to update them. 0.1.34 ------ + * Improvement: New option **tags** for :ref:`needimport` directive * Bugfix: Handling of relative paths in needs builder @@ -1687,6 +1744,7 @@ custom css definitions you need to update them. 0.1.33 ------ + * New feature: Directive :ref:`needimport` implemented * Improvement: needs-builder stores needs.json for all cases in the build directory (like _build/needs/needs.json) (See `issue `_) * Bugfix: Wrong version in needs.json, if an existing needs.json got imported @@ -1696,6 +1754,7 @@ custom css definitions you need to update them. 0.1.32 ------ + * Bugfix: Setting correct working directory during conf.py import * Bugfix: Better config handling, if Sphinx builds gets called multiple times during one single python process. (Configs from prio sphinx builds may still be active.) * Bugifx: Some clean ups for using Sphinx >= 1.6 @@ -1711,6 +1770,7 @@ custom css definitions you need to update them. 0.1.30 ------ + * Improvement: Builder :ref:`needs_builder` added, which exports all needs to a json file. .. _`release:0.1.29`: @@ -1726,7 +1786,7 @@ custom css definitions you need to update them. ------ * Bugfix: Added support for multiple sphinx projects initialisations/builds during a single python process call. - (Reliable sphinx-needs configuration separation) + (Reliable sphinx-needs configuration separation) .. _`release:0.1.27`: @@ -1742,7 +1802,7 @@ custom css definitions you need to update them. ------ * Bugfix: Working placement of "," for links list produced by roles :ref:`role_need_outgoing` - and :ref:`role_need_incoming`. + and :ref:`role_need_incoming`. .. _`release:0.1.25`: @@ -1798,7 +1858,6 @@ custom css definitions you need to update them. * Added configuration parameter :ref:`needs_id_required`. * Backwards compatibility changes: - * Reimplemented **needlist** as alias for ``needfilter`` * Added *need* directive/need as part of the default :ref:`needs_types` configuration. @@ -1811,21 +1870,14 @@ custom css definitions you need to update them. * Free definable need types (Requirements, Bugs, Tests, Employees, ...) * Allowing configuration of needs with a - * directive name * meaningful title * prefix for generated IDs * color - * Added **needfilter** directive * Added layouts for needfilter: - * list (default) * table * diagram (based on plantuml) - * Integrated interaction with the activated plantuml sphinx extension - * Added role **need** to create a reference to a need by giving the id - - diff --git a/docs/contributing.rst b/docs/contributing.rst index 78c502464..65d82ea15 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -71,7 +71,6 @@ or to build with a different builder: # Check links in the documentation CLEAN=true BUILDER=linkcheck tox -e docs-furo - Running Tests ------------- @@ -121,83 +120,81 @@ Also, you need to pass the ``test_server`` fixture to your test function for it .. code-block:: python - # tests/test_sn_collapse_button.py - - import pytest + # tests/test_sn_collapse_button.py + import pytest - @pytest.mark.jstest - @pytest.mark.parametrize( - "test_app", - [ - { - "buildername": "html", - "srcdir": "doc_test/variant_doc", - "tags": ["tag_a"], - "spec_pattern": "js_test/js-test-sn-collapse-button.cy.js" - } - ], - indirect=True, - ) - def test_collapse_button_in_docs(test_app, test_server): - ... -.. note:: + @pytest.mark.jstest + @pytest.mark.parametrize( + "test_app", + [ + { + "buildername": "html", + "srcdir": "doc_test/variant_doc", + "tags": ["tag_a"], + "spec_pattern": "js_test/js-test-sn-collapse-button.cy.js" + } + ], + indirect=True, + ) + def test_collapse_button_in_docs(test_app, test_server): + ... - The ``spec_pattern`` key is required to ensure Cypress locates your test files or folder. Visit this link for more info on how to set the `spec_pattern `_. +.. note:: The ``spec_pattern`` key is required to ensure Cypress locates your test files or folder. Visit this link for more info on how to set the `spec_pattern `_. After you set the ``spec_pattern`` key-value pair as part of the ``test_app`` fixture parameter, you can call ``app.test_js()`` in your Python test case to run a JS test for the ``spec_pattern`` you provided. For example, you can use ``app.test_js()`` like below: .. code-block:: python - # tests/test_sn_collapse_button.py + # tests/test_sn_collapse_button.py - import pytest + import pytest - @pytest.mark.jstest - @pytest.mark.parametrize( - "test_app", - [ - { - "buildername": "html", - "srcdir": "doc_test/variant_doc", - "tags": ["tag_a"], - "spec_pattern": "js_test/js-test-sn-collapse-button.cy.js" - } - ], - indirect=True, - ) - def test_collapse_button_in_docs(test_app, test_server): - """Check if the Sphinx-Needs collapse button works in the provided documentation source.""" - app = test_app - app.build() + @pytest.mark.jstest + @pytest.mark.parametrize( + "test_app", + [ + { + "buildername": "html", + "srcdir": "doc_test/variant_doc", + "tags": ["tag_a"], + "spec_pattern": "js_test/js-test-sn-collapse-button.cy.js" + } + ], + indirect=True, + ) + def test_collapse_button_in_docs(test_app, test_server): + """Check if the Sphinx-Needs collapse button works in the provided documentation source.""" + app = test_app + app.build() - # Call `app.test_js()` to run the JS test for a particular specPattern - js_test_result = app.test_js() + # Call `app.test_js()` to run the JS test for a particular specPattern + js_test_result = app.test_js() - # Check the return code and stdout - assert js_test_result["returncode"] == 0 - assert "All specs passed!" in js_test_result["stdout"].decode("utf-8") + # Check the return code and stdout + assert js_test_result["returncode"] == 0 + assert "All specs passed!" in js_test_result["stdout"].decode("utf-8") .. note:: - ``app.test_js()`` will return a dictionary object containing the ``returncode``, ``stdout``, and ``stderr``. Example: + ``app.test_js()`` will return a dictionary object containing the ``returncode``, ``stdout``, and ``stderr``. Example: - .. code-block:: python + .. code-block:: python - return { - "returncode": 0, - "stdout": "Test passed string", - "stderr": "Errors encountered, - } + return { + "returncode": 0, + "stdout": "Test passed string", + "stderr": "Errors encountered, + } You can run the ``make test-js`` command to check all JS testcases. .. note:: - The ``http_server`` process invoked by the ``make test-js`` command may not terminate properly in some instances. - Kindly check your system's monitoring app to end the process if not terminated automatically. + The ``http_server`` process invoked by the ``make test-js`` command may not terminate properly in some instances. + Kindly check your system's monitoring app to end the process if not terminated automatically. Benchmarks ---------- @@ -215,6 +212,7 @@ source. Publishing a new release ------------------------ + There is a release pipeline installed for the CI. This gets triggered automatically, if a tag is created and pushed. @@ -222,13 +220,12 @@ The tag must follow the format: ``[0-9].[0-9]+.[0-9]``. Otherwise the release jo The release jobs will build the source and wheel distribution and try to upload them. - Structure of the extension's logic ---------------------------------- The following is an outline of the build events which this extension adds to the :ref:`Sphinx build process `: -#. After configuration has been initialised (``config-inited`` event): +1. After configuration has been initialised (``config-inited`` event): - Register additional directives, directive options and warnings (``load_config``) - Check configuration consistency (``check_configuration``) @@ -254,7 +251,6 @@ The following is an outline of the build events which this extension adds to the - Remove ``Need`` nodes marked as ``hidden`` (``analyse_need_locations``) #. When building in parallel mode (``env-merge-info`` event), merge ``BuildEnvironment`` data (``merge_data``) - #. After all documents have been read and transformed (``env-updated`` event) (NOTE these are skipped for ``needs`` builder) - Copy vendored JS libraries (with CSS) to build folder (``install_lib_static_files``) @@ -262,7 +258,6 @@ The following is an outline of the build events which this extension adds to the - Copy vendored CSS files to build folder (``install_styles_static_files``) #. Note, the ``BuildEnvironment`` is cached at this point, only if any documents were updated. - #. For all changed documents, or their dependants (``doctree-resolved``) - Replace all ``Needextract`` nodes with a list of the collected ``Need`` (``process_creator``) @@ -285,4 +280,5 @@ The following is an outline of the build events which this extension adds to the - Print process timing, if ``needs_debug_measurement = True`` (``process_timing``) .. Include our contributors and maintainers. + .. include:: ../AUTHORS diff --git a/docs/directives/list2need.rst b/docs/directives/list2need.rst index 954863b3c..c48845b84 100644 --- a/docs/directives/list2need.rst +++ b/docs/directives/list2need.rst @@ -2,8 +2,8 @@ list2need ========= -.. versionadded:: 1.2.0 +.. versionadded:: 1.2.0 ``list2need`` allows to create need objects out ouf a given list, where each list entry is used to create a single need. @@ -23,7 +23,6 @@ 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:: @@ -39,7 +38,6 @@ For details please see :ref:`list2need_meta_data`. * Sub-Need on level 3. With some rst-syntax support for the **content** by :ref:`list2need` - .. list2need:: :types: req, spec, test :presentation: nested @@ -60,6 +58,7 @@ For details please see :ref:`list2need_meta_data`. List structure -------------- + The used list structure was defined to be as small as possible. Each line starting with a ``*`` will create a new need object. @@ -83,24 +82,22 @@ 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 - + .. 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. :nested: Needs of level 2 are defined in the content of the parent need (level 1) and so on. :standalone: Each list element gets its own, independent need object. They are not nested. - Default: **nested** delimiter @@ -115,6 +112,7 @@ Default: **.** links-down ~~~~~~~~~~ + ``links-down`` set automatically links between the different levels of the list. .. code-block:: rst @@ -148,7 +146,6 @@ The amount of given link-types must be the amount of used levels minus 1. * (NEED-C)Create password hash * (NEED-D)Recalculate hash and compare - tags ~~~~ @@ -165,15 +162,14 @@ tags * (NEED-C)Create password hash * (NEED-D)Recalculate hash and compare - The tags ``A`` and ``B`` are attached to all ``NEED-A``, ``NEED-B``, ``NEED-C`` and ``NEED-D``. - List examples ------------- List with need-ids ~~~~~~~~~~~~~~~~~~ + .. code-block:: rst .. list2need:: @@ -192,6 +188,7 @@ List with need-ids Nested lists ~~~~~~~~~~~~ + .. code-block:: rst .. list2need:: @@ -210,9 +207,9 @@ Nested lists * Level 3 * Level 4 - List with newlines ~~~~~~~~~~~~~~~~~~ + .. code-block:: rst .. list2need:: @@ -241,11 +238,9 @@ Simple rst in lists * Level 1 need with rst. With **some** rst-content for :ref:`list2need` -.. list2need:: +.. list2need:: * Level 1 need with rst. With **some** rst-content for :ref:`list2need` :types: req, spec - * Level 1 need with rst. With **some** rst-content for :ref:`list2need` - rst-directives in lists ~~~~~~~~~~~~~~~~~~~~~~~ @@ -261,7 +256,6 @@ rst-directives in lists :align: center :width: 20% - .. list2need:: :types: req, spec @@ -303,10 +297,11 @@ Lists with need-part support * And a spec need. Lets reference a need-part frm above: :need:`LIST2NEED-REQ-1.1` -.. _list2need_meta_data: +.. _`list2need_meta_data`: Set meta-data ~~~~~~~~~~~~~ + 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`. @@ -330,7 +325,6 @@ And instead of ``"`` also ``'`` can be used. .. needextend:: EXT-FEATURE-B :style: yellow - .. list2need:: :types: feature, req diff --git a/docs/directives/need.rst b/docs/directives/need.rst index 819c701d3..295331085 100644 --- a/docs/directives/need.rst +++ b/docs/directives/need.rst @@ -8,13 +8,13 @@ You can define the type using the correct directive, like ``.. req::`` or ``.. t .. need-example:: - .. req:: User needs to login - :id: ID123 - :status: open - :tags: user;login - :collapse: false + .. 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**. + 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. @@ -23,13 +23,14 @@ but you must set a title as an argument (i.e. if you do not specify :ref:`needs_ .. note:: - By default, the above example works also with ``.. spec::``, ``.. impl::``, ``.. test::`` and all other need types, - which are configured via :ref:`needs_types`. + By default, the above example works also with ``.. spec::``, ``.. impl::``, ``.. test::`` and all other need types, + which are configured via :ref:`needs_types`. -.. _need_diagram: +.. _`need_diagram`: Diagram support --------------- + A need objects can also define it's own PlantUML representation. Therefore Sphinx-Needs looks for the :ref:`needuml` directive inside the content and stores its PlantUML code under given key from :ref:`needuml` directive under the option name ``arch``. @@ -61,12 +62,12 @@ This diagram data can then be used in other :ref:`needuml` calls to combine and 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`. 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. @@ -77,38 +78,40 @@ are representing some kind of a diagram. :style: table :columns: id, type, title - Options for Need Type --------------------- -.. _need_id: +.. _`need_id`: id ~~ + The given ID must match the regular expression (regex) value for the :ref:`needs_id_regex` parameter in **conf.py**. The Sphinx build stops if the ID does not match the regex value. -If you do not specify the id option, we calculate a short hash value based on the title. The calculated value can +If you do not specify the id option, we calculate a short hash value based on the title. The calculated value can also include title if :ref:`needs_id_from_title` is set to **True**. If you don’t change the title, the id will work for all upcoming documentation generations. -.. _need_status: +.. _`need_status`: status ~~~~~~ -A need can only have one status, and the :ref:`needs_statuses` configuration parameter may restrict its selection. +A need can only have one status, and the :ref:`needs_statuses` configuration parameter may restrict its selection. -.. _need_tags: +.. _`need_tags`: tags ~~~~ + You can give multiple tags by separating each with **;** symbol, like ``tag1;tag2;tag3``. White spaces get removed. -.. _need_links: +.. _`need_links`: links ~~~~~ + The ``links`` option can create a link to one or several other needs, no matter the need type. All you must specify is the ID for the need. @@ -126,7 +129,7 @@ You can easily set links to multiple needs by using **;** as a separator. This sets a link to id ``REQ_LINK_1``. -.. _need_extra_links: +.. _`need_extra_links`: extra links +++++++++++ @@ -164,7 +167,7 @@ By using :ref:`needs_extra_links `, you can use the configure Perform some tests -.. _need_delete: +.. _`need_delete`: delete ~~~~~~ @@ -181,9 +184,7 @@ Allowed values (case-insensitive): Default: False -.. note:: - - If you delete a need using the :delete: option, the need will not be part of any filter result. +.. note:: If you delete a need using the :delete: option, the need will not be part of any filter result. .. need-example:: @@ -206,11 +207,11 @@ Default: False Need with ``:delete:`` option not set. - -.. _need_hide: +.. _`need_hide`: hide ~~~~ + There is a **:hide:** option. If this is set to **True**, the need will not be printed in the documentation. But you can use it with **need filters**. @@ -221,10 +222,11 @@ Allowed values (case-insensitive): Default: False -.. _need_collapse: +.. _`need_collapse`: collapse ~~~~~~~~ + If set to **True**, the details section containing status, links or tags is not visible. You can view the details by clicking on the forward arrow symbol near the need title. @@ -251,7 +253,7 @@ Default: False Title, tags, links and everything else is shown directly. -.. _jinja_content: +.. _`jinja_content`: jinja_content ~~~~~~~~~~~~~ @@ -282,40 +284,38 @@ Default: False 'jinja_content': 'true' } - .. need-example:: - .. req:: First Req Need - :id: JINJAID123 - :jinja_content: false + .. req:: First Req Need + :id: JINJAID123 + :jinja_content: false - Need with ``:jinja_content:`` equal to ``false``. + Need with ``:jinja_content:`` equal to ``false``. - .. spec:: Nested Spec Need - :id: JINJAID125 - :status: open - :tags: user;login - :links: JINJAID126 - :jinja_content: + .. spec:: Nested Spec Need + :id: JINJAID125 + :status: open + :tags: user;login + :links: JINJAID126 + :jinja_content: - Nested need with ``:jinja_content:`` option set to ``true``. - This requirement has tags: **{{ tags | join(', ') }}**. + Nested need with ``:jinja_content:`` option set to ``true``. + This requirement has tags: **{{ tags | join(', ') }}**. - It links to: - {% for link in links %} - - {{ link }} - {% endfor %} + It links to: + {% for link in links %} + - {{ link }} + {% endfor %} + .. spec:: First Spec Need + :id: JINJAID126 + :status: open + :jinja_content: - .. spec:: First Spec Need - :id: JINJAID126 - :status: open - :jinja_content: - - Need with ``:jinja_content:`` equal to ``true``. - This requirement has status: **{{ status }}**. + Need with ``:jinja_content:`` equal to ``true``. + This requirement has status: **{{ status }}**. -.. _title_from_content: +.. _`title_from_content`: title_from_content ~~~~~~~~~~~~~~~~~~ @@ -331,21 +331,21 @@ elided title if needed. By default there is no limit to the title length. .. note:: - When using this setting ensure that the first sentence does not contain - any special formatting you would not want in the title (bulleted lists, nested directives, etc.) + When using this setting ensure that the first sentence does not contain + any special formatting you would not want in the title (bulleted lists, nested directives, etc.) If a title is provided and the flag is present, then the provided title will be used and a warning will be issued. .. need-example:: - .. req:: - :title_from_content: + .. 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: +.. _`need_layout`: layout ~~~~~~ @@ -383,8 +383,7 @@ layout Please take a look into :ref:`layouts` for more information. - -.. _need_style: +.. _`need_style`: style ~~~~~ @@ -436,7 +435,7 @@ which leads to the CSS class ``needs_style_open`` if the ``status`` option is se :tags: style_example :style: [[copy("status")]] -.. _need_template: +.. _`need_template`: template ~~~~~~~~ @@ -477,7 +476,7 @@ the ``debug`` :ref:`layout `. You can automatically assign templates to specific needs by using :ref:`needs_global_options`. -.. _need_pre_template: +.. _`need_pre_template`: pre_template ~~~~~~~~~~~~ @@ -500,7 +499,7 @@ For example, you can use it to set a section name before each **need**. This is my **specification** content. -.. _need_post_template: +.. _`need_post_template`: post_template ~~~~~~~~~~~~~ @@ -524,7 +523,7 @@ You can use it to show some need-specific analytics, like dependency diagrams or This is my **specification** content. -.. _need_duration: +.. _`need_duration`: duration ~~~~~~~~ @@ -535,8 +534,7 @@ Track the duration of a need. The need allows any value but the :ref:`needgantt` directive uses and interprets it as days by default. - -.. _need_completion: +.. _`need_completion`: completion ~~~~~~~~~~ @@ -547,7 +545,6 @@ Track the completion of a need. The need allows any value but the :ref:`needgantt` directive uses and interprets it as percentage by default. - Customized Options ------------------ diff --git a/docs/directives/needarch.rst b/docs/directives/needarch.rst index 79bf209e3..0c4af807d 100644 --- a/docs/directives/needarch.rst +++ b/docs/directives/needarch.rst @@ -1,5 +1,3 @@ - - .. _needarch: needarch @@ -12,7 +10,7 @@ jinja functions :ref:`needarch_jinja_need` and :ref:`needarch_jinja_import`. .. req:: Requirement arch :id: req_arch_001 - + .. needarch:: :scale: 50 :align: center @@ -23,10 +21,9 @@ jinja functions :ref:`needarch_jinja_need` and :ref:`needarch_jinja_import`. Jinja context ------------- -The following Jinja functions are **only available** for :ref:`needarch`. +The following Jinja functions are **only available** for :ref:`needarch`. - -.. _needarch_jinja_need: +.. _`needarch_jinja_need`: need() ~~~~~~ @@ -54,8 +51,7 @@ The ``need()`` function provides you the need information the :ref:`needarch` is {% endfor %} } - -.. _needarch_jinja_import: +.. _`needarch_jinja_import`: import(need_links_option_name) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -89,7 +85,7 @@ Then it executes :ref:`needuml_jinja_uml` automatically for all links/need_ids d {{import("checks", "tests")}} -.. _needarch_ex_loop: +.. _`needarch_ex_loop`: NeedArch Loop Example --------------------- diff --git a/docs/directives/needbar.rst b/docs/directives/needbar.rst index e824d2390..17075d68b 100644 --- a/docs/directives/needbar.rst +++ b/docs/directives/needbar.rst @@ -1,7 +1,7 @@ .. _needbar: needbar -======== +======= .. versionadded:: 0.7.5 @@ -21,8 +21,8 @@ The amount of found needs by the filter string is then used as value. .. note:: - This generates multiple image files per ``needbar`` and allows - the document engine to pick the appropriate image type (vector or raster). + This generates multiple image files per ``needbar`` and allows + the document engine to pick the appropriate image type (vector or raster). Options ------- @@ -126,6 +126,7 @@ axis title You can enable axis titles on the barchart by setting the ``:x_axis_title:`` or ``:y_axis_title:`` options. .. hint:: + 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. @@ -151,6 +152,7 @@ The amount of labels must match the amount of values/lines from content. |br| Also, you can set the ``:xlabels:`` and/or ``:ylabels:`` value to ``FROM_DATA`` to fetch the labels from the content. .. hint:: + In a normal bar chart, we use the ``:xlabels:`` as the labels of the x-axis on the chart and the ``:ylabels:`` as the labels of legend. But if you use `horizontal`_ or `transpose`_, the meaning of ``:x_axis_title:`` and ``:y_axis_title:`` will change automatically. @@ -178,7 +180,6 @@ Also, you can set the ``:xlabels:`` and/or ``:ylabels:`` value to ``FROM_DATA`` X,15,10,20 W,20,15,10 - stacked ~~~~~~~ @@ -222,7 +223,6 @@ The ``:show_sum:`` flag does not support any values and it's useful with the ``s 15,10,20 20,15,10 - show_top_sum ~~~~~~~~~~~~ @@ -258,6 +258,7 @@ You can render the bar chart with horizontal bars by setting the ``:horizontal:` The ``:horizontal:`` flag does not support any values and it's useful with the ``stacked`` option enabled. .. hint:: + 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`_. @@ -294,6 +295,7 @@ The idea is, you can try to see the data from different point of view, without r The ``:transpose:`` flag does not support any values and it's useful with big content tables. .. hint:: + * 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. @@ -321,7 +323,6 @@ The ``:transpose:`` flag does not support any values and it's useful with big co X,15,10,20 W,20,15,10 - rotation ~~~~~~~~ @@ -329,7 +330,6 @@ rotation | Use ``:ylabels_rotation:`` to set rotation of labels for y-axis on the diagram. | Use ``:sum_rotation:`` to set rotation of labels for bars on the diagram. - .. need-example:: .. needbar:: rotation example @@ -376,6 +376,7 @@ for a complete list of color names. But besides names, ``:colors:`` options also supports hex-values like ``#ffcc00``. .. hint:: + In a normal bar chart, we use the ``:colors:`` for the legend and bars itself. 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. diff --git a/docs/directives/needextend.rst b/docs/directives/needextend.rst index d8583acc2..189c59853 100644 --- a/docs/directives/needextend.rst +++ b/docs/directives/needextend.rst @@ -2,6 +2,7 @@ needextend ========== + .. versionadded:: 0.7.0 ``needextend`` allows to modify existing needs. It doesn't provide any output, as the modifications @@ -68,10 +69,11 @@ Also, you can add links or delete tags. Options ------- -.. _needextend_strict: +.. _`needextend_strict`: strict ~~~~~~ + The purpose of the ``:strict:`` option is to handle whether an exception gets thrown or a warning log message gets written, if there is no need object to match the ``needextend's`` required argument (e.g. an ID). If you set the ``:strict:`` option value to ``true``, @@ -89,8 +91,8 @@ Default: false .. note:: - We have a configuration (conf.py) option called :ref:`needs_needextend_strict` - that deactivates or activates the ``:strict:`` option behaviour for all ``needextend`` directives in a project. + We have a configuration (conf.py) option called :ref:`needs_needextend_strict` + that deactivates or activates the ``:strict:`` option behaviour for all ``needextend`` directives in a project. Extending needs in current page ------------------------------- @@ -119,6 +121,7 @@ See also, :ref:`filter_current_page` and :ref:`needs_global_options` for setting Changing links -------------- + Options containing links get handled in two steps: 1. Options for the need are set as above. @@ -161,7 +164,6 @@ Options containing links get handled in two steps: :+links: extend_test_004 .. Same as above, so it should not do anything. - .. But it raises the modified-counter by one. .. needextend:: extend_test_006 @@ -169,6 +171,7 @@ Options containing links get handled in two steps: Monitoring modifications ------------------------ + All needs have this two internal parameters: * ``is_modified``: A boolean value. Defaults to ``False`` diff --git a/docs/directives/needextract.rst b/docs/directives/needextract.rst index 445690182..83ca2bbe0 100644 --- a/docs/directives/needextract.rst +++ b/docs/directives/needextract.rst @@ -22,13 +22,12 @@ For instance, a supplier could get a copy of requirements but would not see all :layout: clean :style: green_border - .. caution:: ``needextract`` supports correct rendering of most, but not all, content coming from the original need. Be careful when using complex content in the original need, like custom roles or directives that require any sphinx transforms. - + ``needextract`` supports the full filtering possibilities of sphinx-needs. Please read :ref:`filter` for more information. @@ -47,7 +46,7 @@ supports need ID as filter argument. Options ------- -.. _needextract_layout: +.. _`needextract_layout`: layout ~~~~~~ @@ -62,7 +61,7 @@ See :ref:`layouts` for a list of available layouts. .. needextract:: EXTRACT_FEATURE_1 :layout: focus_r -.. _needextract_style: +.. _`needextract_style`: style ~~~~~ diff --git a/docs/directives/needflow.rst b/docs/directives/needflow.rst index 2f1032f0a..ebb361978 100644 --- a/docs/directives/needflow.rst +++ b/docs/directives/needflow.rst @@ -65,7 +65,7 @@ Options **needflow** supports the full filtering possibilities of **Sphinx-Needs**. Please see :ref:`filter` for more information. -.. _needflow_engine: +.. _`needflow_engine`: engine ~~~~~~ @@ -75,11 +75,10 @@ engine You can set the engine to use for rendering the flowchart, to either ``plantuml`` (default) or ``graphviz``. -.. _needflow_root_id: -.. _needflow_root_direction: -.. _needflow_root_depth: - -.. _needflow_alt: +.. _`needflow_root_id`: +.. _`needflow_root_direction`: +.. _`needflow_root_depth`: +.. _`needflow_alt`: alt ~~~ @@ -150,7 +149,7 @@ Other need filters are applied on this initial selection of connected needs. :link_types: tests, blocks :show_link_names: -.. _needflow_show_filters: +.. _`needflow_show_filters`: show_filters ~~~~~~~~~~~~ @@ -170,7 +169,7 @@ Adds information of used filters below generated flowchart. :tags: flow_example :show_filters: -.. _needflow_show_legend: +.. _`needflow_show_legend`: show_legend ~~~~~~~~~~~ @@ -191,7 +190,7 @@ for flowcharts. :tags: flow_example :show_legend: -.. _needflow_show_link_names: +.. _`needflow_show_link_names`: show_link_names ~~~~~~~~~~~~~~~ @@ -216,7 +215,7 @@ Setup data can be found in test case document ``tests/doc_test/doc_extra_links`` :tags: flow_example :show_link_names: -.. _needflow_link_types: +.. _`needflow_link_types`: link_types ~~~~~~~~~~ @@ -228,9 +227,8 @@ Must contain a comma separated list of link type names. .. code-block:: rst - .. needflow:: - :link_types: links,blocks - + .. needflow:: + :link_types: links,blocks By default, we show all link_types. @@ -289,7 +287,7 @@ See also :ref:`needs_extra_links` for more details about specific link types. :link_types: tests, blocks :show_link_names: -.. _needflow_config: +.. _`needflow_config`: config ~~~~~~ @@ -379,7 +377,7 @@ For ``needs_graphviz_styles`` they are: - * transparent * Transparent background -.. _needflow_scale: +.. _`needflow_scale`: scale ~~~~~ @@ -400,7 +398,7 @@ We also support the numbers between ``1`` and ``300``. :link_types: tests, blocks :scale: 50 -.. _needflow_highlight: +.. _`needflow_highlight`: highlight ~~~~~~~~~ @@ -425,7 +423,7 @@ sets the border for each need of the needflow to **red** if the need also passes :link_types: tests, blocks :highlight: id in ['spec_flow_002', 'subspec_2'] or type == 'req' -.. _needflow_border_color: +.. _`needflow_border_color`: border_color ~~~~~~~~~~~~ @@ -440,10 +438,9 @@ The value should be written with the :ref:`variant syntax - :option: ... - :status: open - :tags: awesome, nice - :author: me + .. needservice:: + :option: ... + :status: open + :tags: awesome, nice + :author: me - Extra content for each new need + Extra content for each new need In most cases, the service fetches requested data from an external server and creates a need object for each found data-element in the returned data. @@ -29,32 +30,34 @@ These need objects can then be used and referenced as all other need objects, e. Options ------- + Each service can define custom options which may be needed for the service to work correctly. Please take a look into the related service documentation to find out what is needed. .. hint:: - ``needservice`` supports all options available for the :ref:`need` directive and - all custom options defined by :ref:`needs_extra_options`. + ``needservice`` supports all options available for the :ref:`need` directive and + all custom options defined by :ref:`needs_extra_options`. For services provided by **Sphinx-Needs** please take a look into :ref:`services`. -.. _needservice_debug: +.. _`needservice_debug`: 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, for example: .. code-block:: rst - .. needservice:: - :debug: - + .. needservice:: + :debug: Content ------- + The content of ``needservice`` is used as content for all created need objects. A service may deviate from this behavior and define its own usage. @@ -64,6 +67,7 @@ Please take a look into the related service documentation for more information. GitHub Issues Example --------------------- + This example is using the ``github-issues`` service. For details, please take a look into its specific documentation under :ref:`github_service`. @@ -74,7 +78,7 @@ their content. .. need-example:: - .. needservice:: github-issues - :query: repo:useblocks/sphinx-needs node latexpdf - :max_content_lines: 4 - :id_prefix: EXAMPLE_ + .. needservice:: github-issues + :query: repo:useblocks/sphinx-needs node latexpdf + :max_content_lines: 4 + :id_prefix: EXAMPLE_ diff --git a/docs/directives/needtable.rst b/docs/directives/needtable.rst index 8b4d50e86..eb32be3d7 100644 --- a/docs/directives/needtable.rst +++ b/docs/directives/needtable.rst @@ -20,20 +20,19 @@ Options .. note:: - **needtable** supports the full filtering possibilities of **Sphinx-Needs**. - Please see :ref:`filter` for more information. + **needtable** supports the full filtering possibilities of **Sphinx-Needs**. + Please see :ref:`filter` for more information. - -.. _needtable_columns: +.. _`needtable_columns`: columns ~~~~~~~ + A comma/semicolon separated string used to define the position of specific columns. For instance:: - .. needtable:: - :columns: id;title;tags - + .. needtable:: + :columns: id;title;tags This will show the columns *id*, *title* and *tags* in the order given. @@ -66,7 +65,7 @@ Tables with a lot of columns will get a horizontal scrollbar in HTML output. :style: table :columns: id;title;tags;status;docname;lineno,is_external,is_need;is_part;content -.. _needtable_colwidths: +.. _`needtable_colwidths`: colwidths ~~~~~~~~~ @@ -80,16 +79,17 @@ It has the same meaning as the ``width options`` of .. need-example:: - .. needtable:: - :tags: test - :columns: id,title,status - :colwidths: 50,40,10 - :style: table + .. needtable:: + :tags: test + :columns: id,title,status + :colwidths: 50,40,10 + :style: table -.. _needtable_custom_titles: +.. _`needtable_custom_titles`: 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. @@ -100,7 +100,7 @@ The characters ``,`` or ``;`` are not allowed. :columns: id;title as "Headline"; tags as "Labels" :style: table -.. _needtable_show_filters: +.. _`needtable_show_filters`: show_filters ~~~~~~~~~~~~ @@ -115,10 +115,11 @@ If set, we add the used filter above the table: :show_filters: :style: table -.. _needtable_style: +.. _`needtable_style`: style ~~~~~ + Allows you to set a specific style for the current table. Supported values are: @@ -138,7 +139,7 @@ Overrides config parameter :ref:`needs_table_style` if set. .. needtable:: :style: datatables -.. _needtable_show_parts: +.. _`needtable_show_parts`: show_parts ~~~~~~~~~~ @@ -181,7 +182,7 @@ To change the prefix please read :ref:`needs_part_prefix`. :id: table_003 :links: table_001.2 -.. _needtable_style_row: +.. _`needtable_style_row`: style_row ~~~~~~~~~ @@ -194,10 +195,9 @@ Also, you can set specific layout for the row. .. need-example:: - .. needtable:: - :tags: ex_row_color - :style_row: needs_blue_border - + .. needtable:: + :tags: ex_row_color + :style_row: needs_blue_border Row style based on specific need value ...................................... @@ -275,11 +275,11 @@ part of the row style. color: #ffffff; } - -.. _needtable_sort: +.. _`needtable_sort`: sort ~~~~ + .. versionadded:: 0.4.3 Option to sort the filtered-results based on a key. @@ -322,11 +322,11 @@ In this case, we set the sort option to ``status``. So *EX_ROW_3* is above of *E Sorting only works if you use the standard sphinx-table for output: ``:style: table``. By default, tables generated with DatabTables uses Javascript to sort results. - -.. _needtable_class: +.. _`needtable_class`: class ~~~~~ + .. versionadded:: 0.7.4 You can set additional class-names for a ``needtable`` using the ``class`` option. Mostly used for HTML output. @@ -339,7 +339,6 @@ It supports comma separated values and will add classes to the already set class border: 3px solid red; } - .. need-example:: .. needtable:: diff --git a/docs/directives/needuml.rst b/docs/directives/needuml.rst index 2c6ae46c6..46f45233f 100644 --- a/docs/directives/needuml.rst +++ b/docs/directives/needuml.rst @@ -1,5 +1,3 @@ - - .. _needuml: needuml @@ -40,16 +38,16 @@ which allows you to use loops, if-clauses, and it injects data from need-objects card {{needs['COMP_NEEDUML2'].status}} } -.. _needuml_options: +.. _`needuml_options`: Options ------- - -.. _needuml_extra: +.. _`needuml_extra`: extra ~~~~~ + Allows to inject additional key-value pairs into the ``needuml`` rendering. ``:extra:`` must be a comma-separated list, containing *key:value* pairs. @@ -71,17 +69,16 @@ Allows to inject additional key-value pairs into the ``needuml`` rendering. of the need and access them with :ref:`needflow` like in :ref:`needuml` introduction. - -.. _needuml_config: +.. _`needuml_config`: config ~~~~~~ + Allows to preconfigure PlantUML and set certain layout options. For details please take a look into needflow :ref:`needflow_config`. - -.. _needuml_debug: +.. _`needuml_debug`: debug ~~~~~ @@ -99,7 +96,7 @@ Helpful to identify reasons why a PlantUML build may have thrown errors. card "Peter" } -.. _needuml_key: +.. _`needuml_key`: key ~~~ @@ -129,7 +126,7 @@ Option ``:key:`` value can't be empty, and can't be ``diagram``. B -> C: Hi C -> B: Hi there -.. _needuml_save: +.. _`needuml_save`: save ~~~~ @@ -137,7 +134,7 @@ save Specifies the file path to store generated Plantuml-code of current ``needuml``. This given file path can be relative path or file name, e.g. ``needuml_group_A/my_needuml.puml`` or ``my_needuml.puml``. -The file will be created and written during each build by +The file will be created and written during each build by using builder :ref:`needumls_builder` or other builder like ``html`` with configuration option :ref:`needs_build_needumls` configured. If given file path already exists, it will be overwritten. @@ -156,18 +153,18 @@ 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``. - -.. _needuml_jinja: +.. _`needuml_jinja`: Jinja context ------------- -When using Jinja statements, the following objects and functions are available. +When using Jinja statements, the following objects and functions are available. -.. _needuml_jinja_needs: +.. _`needuml_jinja_needs`: needs ~~~~~ + A Python dictionary containing all Needs. The ``need_id`` is used as key. .. need-example:: @@ -176,11 +173,11 @@ A Python dictionary containing all Needs. The ``need_id`` is used as key. node "{{needs["FEATURE_NEEDUML1"].title}}" - -.. _needuml_jinja_flow: +.. _`needuml_jinja_flow`: flow(id) ~~~~~~~~ + Loads a Sphinx-Need object as PlantUML object. We use the same layout used for :ref:`needflow`. @@ -192,7 +189,7 @@ This functions represents each Need the same way. the newline, which is normally anyway the case. E.g. see the following example, where the two `flow()` are separated by a newlone. With this approach it is possible to write plantuml code following `flow()`. - E.g. see even the following example, with text following + E.g. see even the following example, with text following `{{flow("COMP_001")}}`. .. need-example:: @@ -204,11 +201,11 @@ This functions represents each Need the same way. card manuall_written } - -.. _needuml_jinja_filter: +.. _`needuml_jinja_filter`: filter(filter_string) ~~~~~~~~~~~~~~~~~~~~~ + Finds a list of Sphinx-Need objects that pass the given filter string. .. need-example:: @@ -219,8 +216,7 @@ Finds a list of Sphinx-Need objects that pass the given filter string. node "{{need.title}}" {% endfor %} - -.. _needuml_jinja_ref: +.. _`needuml_jinja_ref`: ref(id, option, text) ~~~~~~~~~~~~~~~~~~~~~ @@ -229,7 +225,6 @@ Allows to create an hyperlink to a Sphinx-Need object in a PlantUML schema. The 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``. - .. need-example:: .. needuml:: @@ -237,17 +232,17 @@ Sphinx-Need picks the text of the field specified by ``option``), or by the free Alice -> Bob: {{ref("FEATURE_NEEDUML1", option="title")}} Bob -> Alice: {{ref("COMP_NEEDUML2", text="A completely free text")}} -.. _needuml_jinja_uml: +.. _`needuml_jinja_uml`: uml(id) ~~~~~~~ + Loads a Sphinx-Need object as PlantUML object or reuses the stored PlantUML code inside the Sphinx-Need object. If diagram code is available in the need data under ``arch``, the stored PlantUML diagram gets imported. Please read :ref:`need_diagram` for details. - .. need-example:: .. needuml:: @@ -257,8 +252,7 @@ Please read :ref:`need_diagram` for details. {{uml("COMP_001")}} {{uml("FEATURE_NEEDUML1")}} - -.. _needuml_jinja_uml_key: +.. _`needuml_jinja_uml_key`: Key argument ++++++++++++ @@ -276,8 +270,7 @@ inside the need object. {{uml('COMP_002', 'sequence')}} - -.. _needuml_jinja_uml_args: +.. _`needuml_jinja_uml_args`: Additional keyword arguments ++++++++++++++++++++++++++++ @@ -304,7 +297,6 @@ Additional keyword arguments By default **Unknown** is shown, as no variant was set. - Passing ``variant="A"`` parameter to the :ref:`uml() ` function, we get the following: .. need-example:: @@ -323,122 +315,119 @@ Passing ``variant="B"`` parameter to the :ref:`uml() ` functi {{uml("COMP_A_B", variant="B")}} - -.. _needuml_jinja_uml_chain: +.. _`needuml_jinja_uml_chain`: Chaining diagrams +++++++++++++++++ + PlantUML Need objects uses the ``needuml`` directive internally to define their diagrams. All features are available and ``uml()`` can be used multiple time on different levels of a planned architecture. - .. tab-set:: - .. tab-item:: Needs + .. tab-item:: Needs - .. int:: Interface A - :id: INT_A + .. int:: Interface A + :id: INT_A - .. needuml:: + .. needuml:: - circle "Int A" as int + circle "Int A" as int - .. comp:: Component X - :id: COMP_X + .. comp:: Component X + :id: COMP_X - .. needuml:: - - allowmixing + .. needuml:: - {{uml("INT_A")}} - - class "Class A" as cl_a - class "Class B" as cl_b + allowmixing - cl_a o-- cl_b - cl_a --> int + {{uml("INT_A")}} - .. sys:: System RocketScience - :id: SYS_ROCKET + class "Class A" as cl_a + class "Class B" as cl_b - .. needuml:: + cl_a o-- cl_b + cl_a --> int - allowmixing + .. sys:: System RocketScience + :id: SYS_ROCKET - node "RocketScience" as rocket { - {{uml("COMP_X")}} - card "Service Y" as service + .. needuml:: - int --> service - } + allowmixing - And finally a ``needuml`` to make use of the Sphinx-Need system object: + node "RocketScience" as rocket { + {{uml("COMP_X")}} + card "Service Y" as service - .. needuml:: + int --> service + } - allowmixing + And finally a ``needuml`` to make use of the Sphinx-Need system object: - {{uml("SYS_ROCKET")}} + .. needuml:: - actor "A friend" as me #ff5555 + allowmixing - me --> rocket: doing + {{uml("SYS_ROCKET")}} + actor "A friend" as me #ff5555 - .. tab-item:: Code + me --> rocket: doing - .. code-block:: rst + .. tab-item:: Code - .. int:: Interface A - :id: INT_A + .. code-block:: rst - .. needuml:: + .. int:: Interface A + :id: INT_A - circle "Int A" as int + .. needuml:: - .. comp:: Component X - :id: COMP_X + circle "Int A" as int - .. needuml:: + .. comp:: Component X + :id: COMP_X - allowmixing + .. needuml:: - {{uml("INT_A")}} + allowmixing - class "Class A" as cl_a - class "Class B" as cl_b + {{uml("INT_A")}} - cl_a o-- cl_b - cl_a --> int + class "Class A" as cl_a + class "Class B" as cl_b - .. sys:: System RocketScience - :id: SYS_ROCKET + cl_a o-- cl_b + cl_a --> int - .. needuml:: + .. sys:: System RocketScience + :id: SYS_ROCKET - allowmixing + .. needuml:: - node "RocketScience" { - {{uml("COMP_X")}} - card "Service Y" as service + allowmixing - int --> service - } + node "RocketScience" { + {{uml("COMP_X")}} + card "Service Y" as service - And finally a ``needuml`` to make use of the Sphinx-Need system object: + int --> service + } - .. needuml:: + And finally a ``needuml`` to make use of the Sphinx-Need system object: - allowmixing + .. needuml:: - {{uml("SYS_ROCKET")}} + allowmixing - actor "A friend" as me #ff5555 + {{uml("SYS_ROCKET")}} - me --> rocket: doing + actor "A friend" as me #ff5555 + me --> rocket: doing -.. _needuml_example: +.. _`needuml_example`: NeedUml Examples ---------------- @@ -473,22 +462,22 @@ NeedUml Examples .. need-example:: - .. comp:: Component X - :id: COMP_001 + .. comp:: Component X + :id: COMP_001 + + .. needuml:: - .. needuml:: + class "Class X" as class_x { + attribute_1 + attribute_2 + function_1() + function_2() + function_3() + } - 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 "Class Y" as class_y { - attribute_1 - function_1() - } - - class_x o-- class_y + class_x o-- class_y diff --git a/docs/docker.rst b/docs/docker.rst index 066eec40a..a52e9871e 100644 --- a/docs/docker.rst +++ b/docs/docker.rst @@ -8,27 +8,26 @@ Sphinx-Needs Docker Image Status ------ -======================================= ==================== -Image Build Status -======================================= ==================== -``danwos/sphinxneeds:latest`` |sphinxneeds-status| -``danwos/sphinxneeds-latexpdf:latest`` |sphinxneeds-status| -======================================= ==================== +====================================== ==================== +Image Build Status +====================================== ==================== +``danwos/sphinxneeds:latest`` |sphinxneeds-status| +``danwos/sphinxneeds-latexpdf:latest`` |sphinxneeds-status| +====================================== ==================== .. |sphinxneeds-status| image:: https://github.com/useblocks/sphinx-needs/actions/workflows/docker.yaml/badge.svg :target: https://github.com/useblocks/sphinx-needs/actions/workflows/docker.yaml - - Image Variants -------------- The Sphinx-Needs docker images come in two flavors, each designed for a specific -use case. +use case. ``sphinxneeds:`` ~~~~~~~~~~~~~~~~~~~~~ -.. _latest_version: + +.. _`latest_version`: This is the defacto docker image (size ~ 350MB). If you are not sure about what your requirements are, you probably want to use this one. @@ -36,6 +35,7 @@ You can use it as a throw away container (mount your documentation and start the container), as well as the base to build your own docker images. .. note:: + The docker image does not include latex packages and therefore does not support PDF generation. Please use the latex-pdf version below for such use cases. @@ -69,7 +69,6 @@ following tools. This docker image includes all the tools in the :ref:`sphinxneeds:latest ` image and additionally PDF generation tools. The image is ~ 1.5GB large. - Included Tools ^^^^^^^^^^^^^^ @@ -105,7 +104,6 @@ Prerequisites To use the images, install and configure `Docker `__. - Pulling the Image from Docker Hub ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -129,7 +127,6 @@ For example, docker pull danwos/sphinxneeds:0.7.8 - Build The Image Locally ~~~~~~~~~~~~~~~~~~~~~~~ @@ -140,6 +137,7 @@ To build the image locally, execute the following commands. cd docker && ./build_docker.sh .. note:: + The script allows to choose between html and pdf version and the Sphinx-Needs version to be installed. @@ -176,7 +174,7 @@ Generate HTML .. code:: bash - make html + make html For example, @@ -189,7 +187,7 @@ Generate PDF .. code:: bash - make latexpdf + make latexpdf .. note:: Make sure ``danwos/sphinxneeds-latexpdf:latest`` is installed for PDF generation. @@ -202,7 +200,6 @@ Linux docker run --rm -it -v $(pwd):/sphinxneeds danwos/sphinxneeds:latest bash - Windows (cmd) ~~~~~~~~~~~~~ @@ -210,7 +207,6 @@ Windows (cmd) docker run --rm -it -v %cd%:/sphinxneeds danwos/sphinxneeds:latest bash - Windows (Powershell) ~~~~~~~~~~~~~~~~~~~~ @@ -219,4 +215,3 @@ Windows (Powershell) docker run --rm -it -v ${PWD}:/sphinxneeds danwos/sphinxneeds:latest bash Once inside the docker container shell, you can execute :ref:`docs build command ` - diff --git a/docs/dynamic_functions.rst b/docs/dynamic_functions.rst index fd1be0ca0..5d768f616 100644 --- a/docs/dynamic_functions.rst +++ b/docs/dynamic_functions.rst @@ -9,7 +9,7 @@ There are two syntaxes provided to achieve this: - Using double square brackets ``[[...]]`` to encapsulate a dynamic function call. - Using double angled brackets ``<<...>>`` to encapsulate a variant definition. -.. _dynamic_functions: +.. _`dynamic_functions`: Dynamic functions ================= @@ -51,52 +51,52 @@ Dynamic functions can be used for the following directive options: The :ref:`ndf` role replaces the use of the ``[[...]]`` syntax in need content. Built-in functions -------------------- +------------------ The following functions are available by default. -.. note:: - - The parameters ``app``, ``need`` and ``needs`` of the following functions are set automatically. +.. note:: The parameters ``app``, ``need`` and ``needs`` of the following functions are set automatically. test ~~~~ + .. autofunction:: sphinx_needs.functions.common.test .. _echo: echo ~~~~ + .. autofunction:: sphinx_needs.functions.common.echo .. _copy: copy ~~~~ + .. autofunction:: sphinx_needs.functions.common.copy -.. _check_linked_values: +.. _`check_linked_values`: check_linked_values ~~~~~~~~~~~~~~~~~~~ -.. autofunction:: sphinx_needs.functions.common.check_linked_values +.. autofunction:: sphinx_needs.functions.common.check_linked_values -.. _calc_sum: +.. _`calc_sum`: calc_sum ~~~~~~~~ .. autofunction:: sphinx_needs.functions.common.calc_sum -.. _links_content: +.. _`links_content`: links_from_content ~~~~~~~~~~~~~~~~~~ .. autofunction:: sphinx_needs.functions.common.links_from_content - Develop own functions --------------------- @@ -122,26 +122,27 @@ inside your **conf.py** file, to add a :py:class:`.DynamicFunction`: .. code-block:: python - from sphinx_needs.api import add_dynamic_function + from sphinx_needs.api import add_dynamic_function - def my_function(app, need, needs, *args, **kwargs): - # Do magic here - return "some data" + def my_function(app, need, needs, *args, **kwargs): + # Do magic here + return "some data" - def setup(app): - add_dynamic_function(app, my_function) + def setup(app): + add_dynamic_function(app, my_function) Restrictions ~~~~~~~~~~~~ incoming_links ++++++++++++++ + Incoming links are not available when dynamic functions gets calculated. That's because a dynamic function can change outgoing links, so that the incoming links of the target need will be recalculated. This is automatically done but not until all dynamic functions are resolved. -.. _needs_variant_support: +.. _`needs_variant_support`: Variant functions ================= diff --git a/docs/filter.rst b/docs/filter.rst index 5030ee718..75632faf8 100644 --- a/docs/filter.rst +++ b/docs/filter.rst @@ -6,7 +6,7 @@ Filtering needs The filtering of needs and need parts is supported consistently across numerous directives and roles, either by using filter options or by using a filter string. -.. _filter_options: +.. _`filter_options`: Filter options -------------- @@ -27,13 +27,13 @@ For **:status:**, **:tags:** and **:types:** values are separated by "**;**". The logic, if a need belongs to the final result list, is as followed:: - status = (open OR in_progress) AND tags = (user OR login) AND types = (req OR spec) AND eval(filter) is True + status = (open OR in_progress) AND tags = (user OR login) AND types = (req OR spec) AND eval(filter) is True - -.. _option_status: +.. _`option_status`: status ~~~~~~ + 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*. @@ -46,7 +46,7 @@ You can easily filter for multiple statuses by separating them by ";". Example: :status: open :show_status: -.. _option_tags: +.. _`option_tags`: tags ~~~~ @@ -63,10 +63,11 @@ To search for multiple tags, simply separate them by using ";". :tags: main_example :show_tags: -.. _option_types: +.. _`option_types`: types ~~~~~ + For **:types:** the type itself or the human-readable type-title can be used as filter value. .. dropdown:: Show example @@ -76,10 +77,11 @@ For **:types:** the type itself or the human-readable type-title can be used as .. needtable:: :types: test -.. _option_sort_by: +.. _`option_sort_by`: sort_by ~~~~~~~ + Sorts the result list. Allowed values are ``status`` or any alphanumerical property. .. dropdown:: Show example @@ -90,7 +92,7 @@ Sorts the result list. Allowed values are ``status`` or any alphanumerical prope :sort_by: id :status: open -.. _option_filter: +.. _`option_filter`: filter ~~~~~~ @@ -98,7 +100,7 @@ filter The filter option allows the definition of a complex query string, which gets evaluated via eval() in Python. Please see :ref:`filter_string` for more details. -.. _filter_string: +.. _`filter_string`: Filter string ------------- @@ -113,7 +115,6 @@ The usage of a filter string is supported/required by: * :ref:`needbar` * :ref:`needuml` / :ref:`needarch` - The filter string must be a valid Python expression: .. need-example:: @@ -124,9 +125,7 @@ A filter string gets evaluated on needs and need_parts! A need_part inherits all options from its parent need, if the need_part has no own content for this option. E.g. the need_part *content* is kept, but the *status* attribute is taken from its parent need. -.. note:: - - The following attributes are kept inside a need_part: id, title, links_back +.. note:: The following attributes are kept inside a need_part: id, title, links_back This allows to perform searches for need_parts, where search options are based on parent attributes. @@ -144,8 +143,10 @@ Additional variables for :ref:`need_part`: * **id_complete** as Python string. Contains the concatenated ids of parent need and need_part. (compare like ``id_complete != 'ABC_01.03'``) -.. note:: If extra options were specified using :ref:`needs_extra_options` then - those will be available for use in filter expressions as well. +.. note:: + + If extra options were specified using :ref:`needs_extra_options` then + those will be available for use in filter expressions as well. Finally, the following are available: @@ -188,7 +189,7 @@ If it is invalid or returns False, the related need is not taken into account fo .. needlist:: :filter: "filter_example" in tags and (("B" in tags or ("spec" == type and "closed" == status)) or "test" == type) -.. _filter_current_page: +.. _`filter_current_page`: Filtering for needs on the current page ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -205,7 +206,7 @@ to filter for needs only in the same document as the directive. :filter: c.this_doc() :style: datatables -.. _re_search: +.. _`re_search`: search ~~~~~~ @@ -227,7 +228,7 @@ The second parameter should be one of the above variables(status, id, content, . .. needlist:: :filter: search(r"([a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$)", title) -.. _filter_string_performance: +.. _`filter_string_performance`: Filter string performance ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -256,14 +257,15 @@ Also see :ref:`needs_uml_process_max_time`, to guard against long running ``need To debug which filters are being used across your project and their run times, you can enable the :ref:`needs_debug_filters` configuration option. -.. _export_id: +.. _`export_id`: + .. deprecated:: 4.0.0 The directive option ``export_id`` was previously used to export filter information in the ``needs.json`` file. This is deprecated and will be removed in a future version. Instead use the above :ref:`needs_debug_filters` configuration option. -.. _filter_code: +.. _`filter_code`: Filter code ----------- @@ -287,7 +289,7 @@ The code also has access to a variable called ``needs``, which is a :class:`.Nee # which are linked to each other. results = [] - + for need in needs.filter_types(["req"]): for links_id in need['links']: linked_need = needs.get_need(links_id) @@ -305,8 +307,7 @@ If ``filter code`` is used, all other filter related options (like ``status`` or This feature executes every given Python code. So be sure to trust the input/writers. - -.. _filter_func: +.. _`filter_func`: Filter function --------------- @@ -323,8 +324,8 @@ Usage inside a rst file: .. code-block:: rst - .. needtable:: Filter function example - :filter-func: filter_file.own_filter_code + .. needtable:: Filter function example + :filter-func: filter_file.own_filter_code The code of the referenced file ``filter_file.py`` with function ``own_filter_code``: @@ -343,6 +344,7 @@ So it must be part of the Python Path variable. To update this, add Arguments ~~~~~~~~~ + .. versionadded:: 0.7.6 Filter function are supporting arguments: ``filter_file.own_filter_code(value_1,value_2)``. @@ -356,9 +358,8 @@ Example: .. code-block:: rst - .. needtable:: Filter function example - :filter-func: filter_file.own_filter_code(1,2.5,open) - + .. needtable:: Filter function example + :filter-func: filter_file.own_filter_code(1,2.5,open) .. code-block:: @@ -371,6 +372,7 @@ The function developer is responsible to perform any needed typecast. Needpie ~~~~~~~ + :ref:`needpie` also supports filter-code. But instead of needs, a list of resulting numbers must be returned. @@ -382,7 +384,6 @@ Example: :labels: new,done :filter-func: filter_code_func.my_pie_filter_code_args(new,done) - .. code-block:: python def my_pie_filter_code_args(needs, results, **kwargs): @@ -406,7 +407,7 @@ The default text "No needs passed the filter". If this is not intended, add the option -.. _option_filter_warning: +.. _`option_filter_warning`: filter_warning ~~~~~~~~~~~~~~ @@ -450,7 +451,6 @@ More Examples This test checks :need:`IMPL_01` for :need:`OWN_ID_123` inside a Python 2.7 environment. - .. need-example:: Filter result as table .. needtable:: diff --git a/docs/index.rst b/docs/index.rst index 092aa31ba..4bddd7338 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,7 +16,7 @@ Introduction :class: sd-fs-3 .. div:: sd-font-weight-bold - + Bringing Engineering-as-Code to the Sphinx framework. .. div:: sd-fs-5 sd-font-italic @@ -56,128 +56,140 @@ Introduction .. raw:: html :file: _static/flow_chart.svg ----------------- +---------- .. grid:: 1 1 2 2 :gutter: 2 - .. grid-item-card:: :octicon:`checkbox;1.5em;sd-mr-1 fill-primary` Adaptable to your needs + .. grid-item-card:: + + :octicon:`checkbox;1.5em;sd-mr-1 fill-primary` Adaptable to your needs An extension for the `Python `_ based `Sphinx `_ documentation framework, enabling you to define, link, and analyse engineering objects within your documentation, specific to your project, such as features, requirements, specifications, test cases, ... - .. grid-item-card:: :octicon:`shield-check;1.5em;sd-mr-1 fill-primary` Developed for safety + .. grid-item-card:: + + :octicon:`shield-check;1.5em;sd-mr-1 fill-primary` Developed for safety Allows you to define the exact way of using and configuring need objects, to create documentation valid with `ISO 26262 `__, `DO-178B/C `__ or any other safety standard. - .. grid-item-card:: :octicon:`gear;1.5em;sd-mr-1 fill-primary` Highly customizable + .. grid-item-card:: + + :octicon:`gear;1.5em;sd-mr-1 fill-primary` Highly customizable Extensive :ref:`configuration options ` allow you to adapt the extension to your specific needs, and the :ref:`built-in API ` allows other extensions to extend sphinx-needs for specific solutions. - .. grid-item-card:: :octicon:`sync;1.5em;sd-mr-1 fill-primary` Integration with external sources + .. grid-item-card:: + + :octicon:`sync;1.5em;sd-mr-1 fill-primary` Integration with external sources Import and export mechanisms facilitate external synchronization with other tools, such as `JIRA `__, :ref:`GitHub `, or spreadsheets, allowing for embedding tickets, requirements and other information into your documentation. - .. grid-item-card:: :octicon:`dependabot;1.5em;sd-mr-1 fill-primary` Automated data handling + .. grid-item-card:: + + :octicon:`dependabot;1.5em;sd-mr-1 fill-primary` Automated data handling :ref:`dynamic_functions` allow you to handle complex data chains between needs, to load and set changeable data automatically during the documentation generation phase. - .. grid-item-card:: :octicon:`workflow;1.5em;sd-mr-1 fill-primary` PlantUML integration + .. grid-item-card:: + + :octicon:`workflow;1.5em;sd-mr-1 fill-primary` PlantUML integration Allows for the creation of specific objects for architecture elements, which can be reused and recombined in different flow diagrams and higher architecture elements, using `PlantUML `__. ----------------- +---------- .. _other-extensions: See more from `useblocks `__ to enhance your sphinx-needs experience: .. grid:: 1 1 2 2 - :gutter: 2 + :gutter: 2 - .. grid-item-card:: - :link: https://useblocks.com - :img-top: /_static/useblocks-logo-long-dark.svg - :img-alt: https://useblocks.com - :class-img-top: sd-p-3 sd-bg-dark - :class-card: border + .. grid-item-card:: + :link: https://useblocks.com + :img-top: /_static/useblocks-logo-long-dark.svg + :img-alt: https://useblocks.com + :class-img-top: sd-p-3 sd-bg-dark + :class-card: border - Provides an oversight of the useblocks ecosystem, and its goal to bring Engineering-as-Code to the software development process. - +++ + Provides an oversight of the useblocks ecosystem, and its goal to bring Engineering-as-Code to the software development process. + +++ - .. button-link:: https://useblocks.com - :color: primary - :outline: - :align: center - :expand: + .. button-link:: https://useblocks.com + :color: primary + :outline: + :align: center + :expand: - :octicon:`globe;1em;sd-text-primary` useblocks.com + :octicon:`globe;1em;sd-text-primary` useblocks.com - .. grid-item-card:: - :link: https://sphinx-bazel.readthedocs.io/en/latest/ - :img-top: /_images/logos/sphinx_bazel_logo.png - :img-alt: Sphinx-Bazel - :class-card: border + .. grid-item-card:: + :link: https://sphinx-bazel.readthedocs.io/en/latest/ + :img-top: /_images/logos/sphinx_bazel_logo.png + :img-alt: Sphinx-Bazel + :class-card: border - Provides a Bazel domain in Sphinx documentation and allows the automated import of Bazel files and their documentation. - +++ + Provides a Bazel domain in Sphinx documentation and allows the automated import of Bazel files and their documentation. + +++ - .. button-link:: https://sphinx-bazel.readthedocs.io/en/latest/ - :color: primary - :outline: - :align: center - :expand: + .. button-link:: https://sphinx-bazel.readthedocs.io/en/latest/ + :color: primary + :outline: + :align: center + :expand: - :octicon:`book;1em;sd-text-primary` Technical Docs + :octicon:`book;1em;sd-text-primary` Technical Docs - .. grid-item-card:: - :link: https://sphinx-collections.readthedocs.io/en/latest/ - :img-top: /_images/logos/sphinx_collections_logo.png - :img-alt: Sphinx-Collections - :class-img-top: sd-p-2 sd-bg-white - :class-card: border + .. grid-item-card:: + :link: https://sphinx-collections.readthedocs.io/en/latest/ + :img-top: /_images/logos/sphinx_collections_logo.png + :img-alt: Sphinx-Collections + :class-img-top: sd-p-2 sd-bg-white + :class-card: border - Extension to collect or generate files from different sources and include them in the Sphinx source folder. + Extension to collect or generate files from different sources and include them in the Sphinx source folder. - It supports sources like Git repositories, Jinja based files or symlinks. - +++ + It supports sources like Git repositories, Jinja based files or symlinks. + +++ - .. button-link:: https://sphinx-collections.readthedocs.io/en/latest/ - :color: primary - :outline: - :align: center - :expand: + .. button-link:: https://sphinx-collections.readthedocs.io/en/latest/ + :color: primary + :outline: + :align: center + :expand: - :octicon:`book;1em;sd-text-primary` Technical Docs + :octicon:`book;1em;sd-text-primary` Technical Docs - .. grid-item-card:: - :link: https://sphinx-test-reports.readthedocs.io/en/latest/ - :img-top: /_images/logos/sphinx-test-reports-logo.png - :img-alt: Sphinx-Test-Reports - :class-card: border + .. grid-item-card:: + :link: https://sphinx-test-reports.readthedocs.io/en/latest/ + :img-top: /_images/logos/sphinx-test-reports-logo.png + :img-alt: Sphinx-Test-Reports + :class-card: border - Extension to import test results from XML files as **need** objects. + Extension to import test results from XML files as **need** objects. - Created **need** objects can be filtered and linked to specification objects. - +++ + Created **need** objects can be filtered and linked to specification objects. + +++ - .. button-link:: https://sphinx-test-reports.readthedocs.io/en/latest/ - :color: primary - :outline: - :align: center - :expand: + .. button-link:: https://sphinx-test-reports.readthedocs.io/en/latest/ + :color: primary + :outline: + :align: center + :expand: - :octicon:`book;1em;sd-text-primary` Technical Docs + :octicon:`book;1em;sd-text-primary` Technical Docs ----------------- +---------- Contents -------- diff --git a/docs/installation.rst b/docs/installation.rst index c8d81feda..4b52b9722 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -4,52 +4,48 @@ Installation ============ .. .. only:: html - -.. .. image:: https://img.shields.io/pypi/dm/sphinx-needs.svg -.. :target: https://pypi.python.org/pypi/sphinx-needs -.. :alt: Downloads -.. .. image:: https://img.shields.io/pypi/l/sphinx-needs.svg -.. :target: https://pypi.python.org/pypi/sphinx-needs -.. :alt: License -.. .. image:: https://img.shields.io/pypi/pyversions/sphinx-needs.svg -.. :target: https://pypi.python.org/pypi/sphinx-needs -.. :alt: Supported versions -.. .. image:: https://readthedocs.org/projects/sphinx-needs/badge/?version=latest -.. :target: https://readthedocs.org/projects/sphinx-needs/ -.. :alt: ReadTheDocs -.. .. image:: https://github.com/useblocks/sphinx-needs/actions/workflows/ci.yaml/badge.svg -.. :target: https://github.com/useblocks/sphinx-needs/actions -.. :alt: GitHub CI Action status -.. .. image:: https://img.shields.io/pypi/v/sphinx-needs.svg -.. :target: https://pypi.python.org/pypi/sphinx-needs -.. :alt: PyPI Package latest release +.. .. image:: https://img.shields.io/pypi/dm/sphinx-needs.svg +.. :target: https://pypi.python.org/pypi/sphinx-needs +.. :alt: Downloads +.. .. image:: https://img.shields.io/pypi/l/sphinx-needs.svg +.. :target: https://pypi.python.org/pypi/sphinx-needs +.. :alt: License +.. .. image:: https://img.shields.io/pypi/pyversions/sphinx-needs.svg +.. :target: https://pypi.python.org/pypi/sphinx-needs +.. :alt: Supported versions +.. .. image:: https://readthedocs.org/projects/sphinx-needs/badge/?version=latest +.. :target: https://readthedocs.org/projects/sphinx-needs/ +.. :alt: ReadTheDocs +.. .. image:: https://github.com/useblocks/sphinx-needs/actions/workflows/ci.yaml/badge.svg +.. :target: https://github.com/useblocks/sphinx-needs/actions +.. :alt: GitHub CI Action status +.. .. image:: https://img.shields.io/pypi/v/sphinx-needs.svg +.. :target: https://pypi.python.org/pypi/sphinx-needs +.. :alt: PyPI Package latest release Using pip --------- .. code-block:: bash - pip install sphinx-needs + pip install sphinx-needs If you wish to also use the plotting features of sphinx-needs (see :ref:`needbar` and :ref:`needpie`), you need to also install ``matplotlib``, which is available *via* the ``plotting`` extra: .. code-block:: bash - pip install sphinx-needs[plotting] - -.. note:: + pip install sphinx-needs[plotting] - Prior to version **1.0.1** the package was named ``sphinxcontrib-needs``. +.. note:: Prior to version **1.0.1** the package was named ``sphinxcontrib-needs``. Using sources ------------- .. code-block:: bash - git clone https://github.com/useblocks/sphinx-needs - cd sphinx-needs - pip install . - + git clone https://github.com/useblocks/sphinx-needs + cd sphinx-needs + pip install . Activation ---------- @@ -62,7 +58,7 @@ For final activation, please add ``sphinx_needs`` to the project's extension lis For the full configuration, please read :ref:`config`. -.. _install_theme: +.. _`install_theme`: HTML Theme support ------------------ @@ -76,10 +72,10 @@ In particular, `CSS Variables`_ are used to specify the coloring of most compone The default values are as follows (see also :ref:`needs_css`): .. dropdown:: Default CSS Variables - :icon: paintbrush + :icon: paintbrush - .. literalinclude:: ../sphinx_needs/css/themes/modern.css - :language: css + .. literalinclude:: ../sphinx_needs/css/themes/modern.css + :language: css These variables can be overridden by adding your own CSS file to the Sphinx project (see `this how-to`_). @@ -87,39 +83,38 @@ These variables can be overridden by adding your own CSS file to the Sphinx proj For examples of how to adjust the CSS, this documentation is configured to build against multiple themes using the following CSS: .. dropdown:: furo - :icon: paintbrush + :icon: paintbrush - .. literalinclude:: _static/_css/furo.css - :language: css - :start-after: /* doc config start */ - :end-before: /* doc config end */ + .. literalinclude:: _static/_css/furo.css + :language: css + :start-after: /* doc config start */ + :end-before: /* doc config end */ .. dropdown:: pydata-sphinx-theme - :icon: paintbrush + :icon: paintbrush - .. literalinclude:: _static/_css/pydata_sphinx_theme.css - :language: css - :start-after: /* doc config start */ - :end-before: /* doc config end */ + .. literalinclude:: _static/_css/pydata_sphinx_theme.css + :language: css + :start-after: /* doc config start */ + :end-before: /* doc config end */ .. dropdown:: sphinx-rtd-theme - :icon: paintbrush + :icon: paintbrush - .. literalinclude:: _static/_css/sphinx_rtd_theme.css - :language: css + .. literalinclude:: _static/_css/sphinx_rtd_theme.css + :language: css .. dropdown:: sphinx-immaterial - :icon: paintbrush + :icon: paintbrush - .. literalinclude:: _static/_css/sphinx_immaterial.css - :language: css - :start-after: /* doc config start */ - :end-before: /* doc config end */ + .. literalinclude:: _static/_css/sphinx_immaterial.css + :language: css + :start-after: /* doc config start */ + :end-before: /* doc config end */ -.. _CSS Variables: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties +.. _css variables: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties .. _this how-to: https://docs.readthedocs.io/en/stable/guides/adding-custom-css.html - -.. _install_plantuml: +.. _`install_plantuml`: PlantUML support ---------------- @@ -129,7 +124,6 @@ Sphinx-extension `sphinxcontrib-plantuml `_. ReadTheDocs provides ``plantuml.jar`` already on their system, so do not store it inside your source version control system. - Using Docker ------------ @@ -171,11 +163,11 @@ Sphinx-Needs is also available as a Docker Image. See :ref:`docker` for the documentation and hints how to use it. .. _ide: -.. _ide_vscode: +.. _`ide_vscode`: VS Code Extension ----------------- -The VS Code extension `ubCode `_ provides +The VS Code extension `ubCode `_ provides support for Sphinx-Needs. See more details in the `Documentation `_. diff --git a/docs/layout_styles.rst b/docs/layout_styles.rst index 7adc99782..d1bc892cb 100644 --- a/docs/layout_styles.rst +++ b/docs/layout_styles.rst @@ -1,4 +1,4 @@ -.. _layouts_styles: +.. _`layouts_styles`: Layouts & Styles ================ @@ -20,6 +20,7 @@ Both features can be set directly during need-configuration or inside the sphinx Layouts ------- + Layouts are using a predefined :ref:`grid system ` and define which data shall be shown in which grid-cells. There can be multiple layouts using the same :ref:`grid system `, but maybe showing different data. @@ -78,7 +79,6 @@ Most useful layouts are: This is a need using **FOCUS layout**. The same meta is set as the two needs above. - There are also some *extensions* for the layouts above available: .. list-table:: @@ -130,7 +130,7 @@ If you need another field as source, you must create your own layout. :id: EX_CLEAN_R :status: open :tags: a, b, c, example - :image: _images/needs_logo.png + :image: _images/needs_logo.png :layout: clean_r This is a need using **CLEAN_R layout**. @@ -139,7 +139,7 @@ If you need another field as source, you must create your own layout. :id: EX_CLEAN_LP :status: open :tags: a, b, c, example - :image: _images/needs_logo.png + :image: _images/needs_logo.png :layout: clean_lp This is a need using **CLEAN_LP layout**. @@ -148,7 +148,7 @@ If you need another field as source, you must create your own layout. :id: EX_CLEAN_RP :status: open :tags: a, b, c, example - :image: _images/needs_logo.png + :image: _images/needs_logo.png :layout: clean_rp This is a need using **CLEAN_RP layout**. @@ -177,7 +177,6 @@ If you need another field as source, you must create your own layout. This is a need using **FOCUS_R layout**. - Special layouts: .. list-table:: @@ -205,38 +204,39 @@ Special layouts: Using layouts ~~~~~~~~~~~~~ + There are two ways of setting a layout for a need: Set it globally via :ref:`needs_default_layout` in your **conf.py** file:: - # conf.py - needs_default_layout = 'complete' + # conf.py + needs_default_layout = 'complete' Or set it locally for each need by using :ref:`need_layout` option:: - .. req:: My requirement - :layout: complete - + .. req:: My requirement + :layout: complete -.. _own_layouts: +.. _`own_layouts`: Defining own layouts ~~~~~~~~~~~~~~~~~~~~ + Own layouts can be defined by using the the config parameter :ref:`needs_layouts` in your **conf.py** file. ``needs_layouts`` must be a dictionary and each key represents a layout. A layout must define the used grid-system and a layout-structure. Example:: - needs_layouts = { - 'my_layout': { - 'grid': 'simple', - 'layout': { - 'head': ['my custom head'] - 'meta': [ 'my first meta line', - 'my second meta line'] - } - } - } + needs_layouts = { + 'my_layout': { + 'grid': 'simple', + 'layout': { + 'head': ['my custom head'] + 'meta': [ 'my first meta line', + 'my second meta line'] + } + } + } The ``layout-structure`` must also be a dictionary, where each key reference an area in the used grid system. By default these can be: ``head``, ``meta``, ``footer`` and more. @@ -252,18 +252,16 @@ This line can contain :ref:`layout_functions`, which care about getting need-dat **Sphinx-Needs** provides some default layouts. These layouts can **not** be overwritten. See :ref:`layout list ` for more information. -.. note:: - - The ``content`` area of a grid can not be overwritten. It is always there and can't be changed or replaced. - +.. note:: The ``content`` area of a grid can not be overwritten. It is always there and can't be changed or replaced. -.. _layout_line: +.. _`layout_line`: Layout line +++++++++++ + A layout line may look like this:: - **style**: my_<>_style + **style**: my_<>_style This line contains: @@ -282,7 +280,7 @@ You can combine as many :ref:`layout_functions` and text elements as you want fo The head-line for the default Sphinx-Needs layout ``clean`` looks like this:: - <>: **<>** <> <> + <>: **<>** <> <> You are free to surround a layout function with a rst role. Like ``**<>**`` to get a bold printed title. @@ -293,7 +291,7 @@ As example, there may be an ``author`` option in a bug-need and you want to show The line for the ``side`` area could look like:: - '<>' + '<>' .. spec:: My test spec :author: daniel @@ -342,7 +340,7 @@ Here is the complete used code :tags: example :style: yellow, blue_border -.. _layout_functions: +.. _`layout_functions`: Layout functions ++++++++++++++++ @@ -384,6 +382,7 @@ Available layout functions are: Styles ------ + Styles handle mostly colors for background, border and co. for a need. Their definition is done in css files, so that **Sphinx-Needs** only cares about setting the correct class in HTML output. This also means that styles do not have any impact to the need design in PDFs and other output formats. @@ -521,29 +520,30 @@ Different styles can also be combined by setting a comma-separated string: ``yel Using styles ~~~~~~~~~~~~ + There are two ways of setting a style for a need: Set it globally via :ref:`needs_default_style` in your **conf.py** file:: - # conf.py - needs_default_style = 'red' + # conf.py + needs_default_style = 'red' Or set it locally for each need by using :ref:`need_style` option:: - .. req:: My requirement - :style: red + .. req:: My requirement + :style: red By setting a style to ``None``, no style is set and the normal Sphinx-Needs style is used. Own style configuration -~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~ If you need to customize the css definitions, there are two ways of doing it: * Provide a css file by using :ref:`needs_css` * Set own css on sphinx level -.. _styles_css: +.. _`styles_css`: Sphinx-needs CSS option +++++++++++++++++++++++ @@ -565,7 +565,7 @@ Sphinx-needs provides the following css styles: .. image:: /_images/need_dark.png -.. _own_css: +.. _`own_css`: Own CSS file on sphinx level ++++++++++++++++++++++++++++ @@ -573,14 +573,14 @@ Own CSS file on sphinx level If you want to use most of the sphinx-needs internal styles but only need some specific changes for single elements, you can provide your own CSS file by register it inside your conf.py:: - html_css_files = ['css/my_custom.css'] - + html_css_files = ['css/my_custom.css'] + See `html_css_files `_ for changing priority or media type. .. hint:: - Do not name it **custom.css** if you are using `Read the docs `_ as - this name is already taken. + Do not name it **custom.css** if you are using `Read the docs `_ as + this name is already taken. HTML output ----------- @@ -588,7 +588,7 @@ HTML output For **html output** the used layout and style names are added as css-class to the need table object. Beside this also the used grid system is added:: - +
The above line contains the following css classes: @@ -606,15 +606,17 @@ So if a user defined layout has the name ``specification_layout``, the related c Grids ----- + The following grids are available. Simple grids ~~~~~~~~~~~~ -.. _grid_simple: +.. _`grid_simple`: simple ++++++ + This is the default layout used by **Sphinx-Needs**. .. table:: @@ -628,7 +630,7 @@ This is the default layout used by **Sphinx-Needs**. | content | +---------+ -.. _grid_simple_footer: +.. _`grid_simple_footer`: simple_footer +++++++++++++ @@ -646,7 +648,7 @@ simple_footer | footer | +---------+ -.. _grid_simple_side_left: +.. _`grid_simple_side_left`: simple_side_left ++++++++++++++++ @@ -662,8 +664,7 @@ simple_side_left | | content | +------+---------+ - -.. _grid_simple_side_right: +.. _`grid_simple_side_right`: simple_side_right +++++++++++++++++ @@ -671,7 +672,6 @@ simple_side_right .. table:: :class: needs_grid_example - +---------+------+ | head | side | +---------+ | @@ -680,8 +680,7 @@ simple_side_right | content | | +---------+------+ - -.. _grid_simple_side_left_partial: +.. _`grid_simple_side_left_partial`: simple_side_left_partial ++++++++++++++++++++++++ @@ -697,7 +696,7 @@ simple_side_left_partial | content | +-------------+ -.. _grid_simple_side_right_partial: +.. _`grid_simple_side_right_partial`: simple_side_right_partial +++++++++++++++++++++++++ @@ -716,7 +715,7 @@ simple_side_right_partial Complex grids ~~~~~~~~~~~~~ -.. _grid_complex: +.. _`grid_complex`: complex +++++++ @@ -724,20 +723,20 @@ complex .. table:: :class: needs_grid_example - +-------------+--------+--------------+ - | head_left | head | head_right | - +-------------+----+---+--------------+ - | meta_left | meta_right | - +------------------+------------------+ - | content | - +-------------+--------+--------------+ - | footer_left | footer | footer_right | - +-------------+--------+--------------+ + +-------------+------------+--------------+ + | head_left | head | head_right | + +-------------+-----+------+--------------+ + | meta_left | meta_right | + +-------------------+---------------------+ + | content | + +-------------+------------+--------------+ + | footer_left | footer | footer_right | + +-------------+------------+--------------+ Content focused grids ~~~~~~~~~~~~~~~~~~~~~ -.. _grid_content: +.. _`grid_content`: content +++++++ @@ -749,7 +748,7 @@ content | content | +---------+ -.. _grid_content_footer: +.. _`grid_content_footer`: content_footer ++++++++++++++ @@ -763,7 +762,7 @@ content_footer | footer | +---------+ -.. _grid_content_side_left: +.. _`grid_content_side_left`: content_side_left +++++++++++++++++ @@ -775,7 +774,7 @@ content_side_left | side | content | +------+---------+ -.. _grid_content_side_right: +.. _`grid_content_side_right`: content_side_right ++++++++++++++++++ @@ -787,7 +786,7 @@ content_side_right | content | side | +---------+------+ -.. _grid_content_footer_side_left: +.. _`grid_content_footer_side_left`: content_footer_side_left ++++++++++++++++++++++++ @@ -795,13 +794,13 @@ content_footer_side_left .. table:: :class: needs_grid_example - +--------+---------+ - | side | content | - | +---------+ - | | footer | - +--------+---------+ + +------+---------+ + | side | content | + | +---------+ + | | footer | + +------+---------+ -.. _grid_content_footer_side_right: +.. _`grid_content_footer_side_right`: content_footer_side_right +++++++++++++++++++++++++ diff --git a/docs/performance/debug.rst b/docs/performance/debug.rst index 81cbed01b..1fd549ed9 100644 --- a/docs/performance/debug.rst +++ b/docs/performance/debug.rst @@ -1,4 +1,4 @@ -.. _runtime_debugging: +.. _`runtime_debugging`: Runtime debugging ================= @@ -14,7 +14,7 @@ supports user defined elements and internal functions. To activate it, simply add the following to the project ``conf.py`` file:: - needs_debug_measurement = True + needs_debug_measurement = True This will perform measurements and gives some output in three formats: @@ -29,7 +29,6 @@ This will perform measurements and gives some output in three formats: HTML report example of timing measurements (*Click to open complete HTML report*) - .. warning:: Do not use this function in Sphinx parallel mode, as this will result in incorrect data. @@ -37,7 +36,7 @@ This will perform measurements and gives some output in three formats: Technical details ----------------- -If you need to activate the measurement for additional Sphinx-Needs functions, use the ``measure_time()`` decorator. +If you need to activate the measurement for additional Sphinx-Needs functions, use the ``measure_time()`` decorator. -.. autofunction:: sphinx_needs.debug.measure_time \ No newline at end of file +.. autofunction:: sphinx_needs.debug.measure_time diff --git a/docs/performance/index.rst b/docs/performance/index.rst index 178e37d1f..36f852053 100644 --- a/docs/performance/index.rst +++ b/docs/performance/index.rst @@ -8,4 +8,3 @@ Performance & Profiling script debug - diff --git a/docs/performance/script.rst b/docs/performance/script.rst index 152c03dea..44868efa6 100644 --- a/docs/performance/script.rst +++ b/docs/performance/script.rst @@ -1,4 +1,4 @@ -.. _performance_script: +.. _`performance_script`: Performance & Profiling script ============================== @@ -23,12 +23,14 @@ Test series To start a series of test with some predefined values, run ``python performance_test.py series`` .. .. program-output:: python ../performance/performance_test.py series + .. literalinclude:: series_output.txt But you can modify the details and set some static values by setting various parameters. Just run ``python performance_test.py series --help`` to get an overview .. .. program-output:: python ../performance/performance_test.py series --help + .. literalinclude:: help.txt Also if ``--needs``, ``--pages`` or ``parallel`` is set multiple times, one performance test is executed per it. @@ -37,12 +39,13 @@ Example:: ``python performance_test.py series --needs 1 --needs 10 --pages 1 --p This will set 2 values for ``needs``, 2 for ``pages`` and 2 for parallel. So in the end it will run **8** test configurations (2 needs x 2 pages x 2 parallel = 8). - .. .. program-output:: python ../performance/performance_test.py series --needs 1 --needs 10 --pages 1 --pages 10 --parallel 1 --parallel 4 --needtables 0 --dummies 0 + .. literalinclude:: complex.txt Parallel execution ------------------ + :versionadded: 0.7.1 You may have noticed, the parallel execution on multiple cores can lower the needed runtime. @@ -59,33 +62,36 @@ are used. .. code-block:: text - runtime s pages # needs per page needs # needtables # dummies # parallel cores - ----------- --------- ---------------- --------- -------------- ----------- ---------------- - 169.46 500 10 5000 0 5000 1 - 103.08 500 10 5000 0 5000 8 + runtime s pages # needs per page needs # needtables # dummies # parallel cores + ----------- --------- ---------------- --------- -------------- ----------- ---------------- + 169.46 500 10 5000 0 5000 1 + 103.08 500 10 5000 0 5000 8 Used command: ``python performance_test.py series --needs 10 --pages 500 --dummies 10 --needtables 0 --parallel 1 --parallel 8`` The parallel execution can used by any documentation build , just use ``-j`` option. Example, which uses 4 processes in parallel: ``sphinx-build -j 4 -b html . _build/html`` - Used rst template ----------------- + For all performance tests the same rst-template is used: index ~~~~~ + .. literalinclude:: /../performance/project/index.template pages ~~~~~ + .. literalinclude:: /../performance/project/page.template .. _profiling: Profiling --------- + With option ``--profile NAME`` a code-area specific profile can be activated. Currently supported are: @@ -105,10 +111,9 @@ Simply set a environment variable called ``NEEDS_PROFILING`` and set the value t Example for Linux: ``export NEEDS_PROFILING=NEEDTABLE,NEED_PRINT``. - - Analysing profile ~~~~~~~~~~~~~~~~~ + Use ``snakeviz`` together with ``--profile `` to open automatically a graphical analysis of the generated profile file. @@ -116,7 +121,7 @@ For this ``snakeviz`` must be installed: ``pip install snakeviz``. Example:: - python performance_test.py series --needs 10 --pages 10 --profile NEEDTABLE --profile NEED_PROCESS --snakeviz + python performance_test.py series --needs 10 --pages 10 --profile NEEDTABLE --profile NEED_PROCESS --snakeviz .. image:: /_images/snakeviz_needtable.png :width: 80% @@ -124,13 +129,13 @@ Example:: Measurements ------------ + The measurements were performed with the following setup: * Sphinx-Needs **0.7.0** on **1** core as parallel build is not supported by version. * Sphinx-Needs **0.7.1**, with **1** core. * Sphinx-Needs **0.7.1**, with **4** cores. - .. list-table:: :header-rows: 1 :stub-columns: 1 diff --git a/docs/roles.rst b/docs/roles.rst index fc2edf85f..31dbedcf1 100644 --- a/docs/roles.rst +++ b/docs/roles.rst @@ -5,7 +5,7 @@ Roles You can use Roles to get short information of needs inside single sentences. -.. _role_need: +.. _`role_need`: .. _needref: need @@ -15,7 +15,7 @@ The role ``:need:`` will add title, id and a link to the need. We use it to reference an existing need, without the need to keep title and link location manually in sync. -With ``[[`` and ``]]`` you can refer to defined and set :ref:`extra options `. +With ``[[`` and ``]]`` you can refer to defined and set :ref:`extra options `. .. need-example:: @@ -34,8 +34,8 @@ With ``[[`` and ``]]`` you can refer to defined and set :ref:`extra options `_ + If we find a ``[[`` in the customized string, we handle it + according to Python's ``{`` `.format() `_ function. Please see https://pyformat.info/ for more information. RST-attributes like ``**bold**`` are **not** supported. @@ -45,11 +45,11 @@ With ``[[`` and ``]]`` you can refer to defined and set :ref:`extra options `, the algorithm is different and you will only get the need id as link text. - -.. _role_need_outgoing: +.. _`role_need_outgoing`: need_outgoing ------------- + .. versionadded:: 0.1.25 ``:need_outgoing:`` adds a list of all outgoing links of the given need. @@ -63,10 +63,11 @@ The list contains the need IDs only, no title or any other information is printe To get butter on our bread, we need to fulfill :need_outgoing:`roles_req_2` -.. _role_need_incoming: +.. _`role_need_incoming`: need_incoming ------------- + .. versionadded:: 0.1.25 ``:need_incoming:`` prints a list of IDs of needs which have set outgoing links to the given need. @@ -76,10 +77,11 @@ need_incoming The realisation of **Sliced Bread** is really important because the needs :need_incoming:`roles_req_1` are based on it. -.. _need_part: +.. _`need_part`: need_part / np ----------------- +-------------- + .. versionadded:: 0.3.0 You can use ``:need_part:`` or as shortcut ``:np:`` inside needs to set a sub-id for a specific sentence/part. @@ -101,7 +103,6 @@ The used need_part id can be freely chosen, but should not contain any whitespac And we also need --> :np:`(awesome_3) a turbo button`! - .. spec:: Build awesome car :id: impl_my_car_1 :links: my_car_1.1, my_car_1.2 @@ -111,7 +112,6 @@ The used need_part id can be freely chosen, but should not contain any whitespac 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** @@ -136,10 +136,11 @@ Please see :ref:`needtable_show_parts` of :ref:`needtable` configuration documen :show_parts: :columns: id, title, incoming, outgoing -.. _need_count: +.. _`need_count`: need_count ---------- + .. versionadded:: 0.3.1 Counts found needs for a given filter and shows the final amount. @@ -168,8 +169,7 @@ See :ref:`filter_string` for more information. So if you use :ref:`need_part` , the result may contain the amount of found needs *and* found need_parts. To avoid this, add ``is_need`` or ``is_part`` to your filter. - -.. _need_count_ratio: +.. _`need_count_ratio`: Ratio ~~~~~ @@ -183,11 +183,11 @@ To calculate the ratio of one filter to another filter, you can define two filte :need_count:`status == open and type == "spec" ? type == "spec"` % of our specifications are open. - -.. _need_func: +.. _`need_func`: need_func --------- + .. deprecated:: 3.1.0 Use :ref:`ndf` instead. @@ -196,10 +196,11 @@ need_func ndf --- + .. versionadded:: 3.1.0 Executes a :ref:`need dynamic function ` and uses the return values as content. .. need-example:: - A nice :ndf:`echo("first test")` for dynamic functions. + A nice :ndf:`echo("first test")` for dynamic functions. diff --git a/docs/schema/index.rst b/docs/schema/index.rst index 25314f241..2f6936f46 100644 --- a/docs/schema/index.rst +++ b/docs/schema/index.rst @@ -1065,10 +1065,10 @@ Validation errors include detailed information: identifier built from the :ref:`schema rule id ` and the 0-based index of the rule in the list. Examples:: - [0] > local > properties > id > pattern - spec[1] > local > properties > id > pattern + [0] > local > properties > id > pattern + spec[1] > local > properties > id > pattern - The first example has no schema rule ID defined, so only the index is used. + The first example has no schema rule ID defined, so only the index is used. - **User message**: Optional user-friendly :ref:`message ` set in the schema rules. diff --git a/docs/services/github.rst b/docs/services/github.rst index e72605722..7359f60d0 100644 --- a/docs/services/github.rst +++ b/docs/services/github.rst @@ -1,4 +1,4 @@ -.. _github_service: +.. _`github_service`: GitHub services =============== @@ -10,7 +10,6 @@ for each information type: + ``github-prs`` + ``github-commits`` - They all have common configuration options and are using the same way of querying their data. Therefore the below configuration is valid for all three services. @@ -20,10 +19,10 @@ Each services creates normally multiple need objects for each element found by q .. code-block:: rst - .. needservice:: github-issues - :query: repo:useblocks/sphinx-needs node latexpdf - :max_amount: 1 - :max_content_lines: 4 + .. needservice:: github-issues + :query: repo:useblocks/sphinx-needs node latexpdf + :max_amount: 1 + :max_content_lines: 4 .. figure:: /_images/github_issue_1.png :scale: 80% @@ -37,18 +36,18 @@ Also the content part of ``needservice`` is added as extra data to the end of th .. code-block:: rst - .. needservice:: github-issues - :query: repo:useblocks/sphinx-needs node latexpdf - :id_prefix: GH_ - :max_amount: 1 - :max_content_lines: 4 - :type: spec - :author: Me - :tags: github, awesome, issue, open - :layout: clean - :style: discreet + .. needservice:: github-issues + :query: repo:useblocks/sphinx-needs node latexpdf + :id_prefix: GH_ + :max_amount: 1 + :max_content_lines: 4 + :type: spec + :author: Me + :tags: github, awesome, issue, open + :layout: clean + :style: discreet - Extra content for each new need + Extra content for each new need .. figure:: /_images/github_issue_2.png :scale: 80% @@ -57,6 +56,7 @@ Also the content part of ``needservice`` is added as extra data to the end of th Querying objects ---------------- + There are two options for querying objects for GitHub: :``query``: Performs a Github search @@ -75,6 +75,7 @@ Setting ``query`` or ``specific`` option is mandatory for services ``github-issu query +++++ + The imported objects are based on a query-string, which must be valid to the `Github search syntax for issues and pull requests `_. @@ -87,36 +88,36 @@ This loads all open issues, which have the strings *needtable* and *viewports* i .. code-block:: rst - .. needservice:: github-issues - :query: repo:useblocks/sphinx-needs state:open needtable viewports - + .. needservice:: github-issues + :query: repo:useblocks/sphinx-needs state:open needtable viewports specific ++++++++ + If only a single, specific object shall be documented, using ``query`` will not work, as the GitHub Search API does not support query-options for getting a specific element. Instead use ``specific`` and provide the unique reference in the syntax ``owner/repo/number``, for example ``useblocks/sphinx-needs/155`` - **Example**: This query fetches a specific pull request with the id 161. .. code-block:: rst - .. needservice:: github-prs - :specific: useblocks/sphinx-needs/161 + .. needservice:: github-prs + :specific: useblocks/sphinx-needs/161 .. figure:: /_images/github_issue_3.png :scale: 80% Example of a github Issue collected with Sphinx-Needs. -.. _service_github_config: +.. _`service_github_config`: Common Configuration -------------------- + All GitHub related services have a common set of configuration options and their configuration must be done in :ref:`needs_services` inside the project's **conf.py** file. @@ -128,7 +129,7 @@ The following key-value configuration parameters are known by all GitHub service :username: Username if access to private repositories is needed. :token: Personal GitHub token for login. Can be created in your `User profile page `_. :download_avatars: ``True/False``, if avatars shall be downloaded. If ``False`` a default avatar is used. - Needed mostly for ``GitHub Enterprise``, as authentication for avatars may make some trouble. + Needed mostly for ``GitHub Enterprise``, as authentication for avatars may make some trouble. :download_folder: Folder path for avatar downloads. Default: ``github_images``. :need_type: Default need type to use, if no type got specified in directive options :max_amount: The maximum amount of issues to report @@ -140,26 +141,26 @@ All options can be overwritten by setting them directly in the need service dire .. code-block:: rst - .. needservice:: github-issues - :query: repo:useblocks/sphinx-needs - :type: test - :max_amount: 10 - :max_content_lines: 2 - :id_prefix: GITHUB_UB_ + .. needservice:: github-issues + :query: repo:useblocks/sphinx-needs + :type: test + :max_amount: 10 + :max_content_lines: 2 + :id_prefix: GITHUB_UB_ **Example configuration for conf.py**: .. code-block:: python - needs_services = { - 'github-issues': { - 'url': 'https://api.github.com/', - 'need_type': 'spec', - 'max_amount': 2, - 'max_content_lines': 20, - 'id_prefix': 'GH_ISSUE_' - } - } + needs_services = { + 'github-issues': { + 'url': 'https://api.github.com/', + 'need_type': 'spec', + 'max_amount': 2, + 'max_content_lines': 20, + 'id_prefix': 'GH_ISSUE_' + } + } Layout ++++++ @@ -172,11 +173,11 @@ directive :ref:`needservice`. .. code-block:: rst - .. needservice:: github-issues - :query: repo:useblocks/sphinx-needs node latexpdf - :max_content_lines: 4 - :layout: focus_l - :style: blue_border + .. needservice:: github-issues + :query: repo:useblocks/sphinx-needs node latexpdf + :max_content_lines: 4 + :layout: focus_l + :style: blue_border .. figure:: /_images/github_issue_4.png :scale: 80% @@ -185,6 +186,7 @@ directive :ref:`needservice`. Need type +++++++++ + The GitHub services create 3 new need types: ``issue``, ``pr`` and ``commit``. These types are used by default by the related service, but its usage can be overwritten in the service configuration by setting ``need_type`` or in the directive directly by setting ``type``. @@ -192,10 +194,11 @@ by setting ``need_type`` or in the directive directly by setting ``type``. The configuration (names, colors, diagram representation) can also be overwritten by configuring your own need type in the configuration. Simply use :ref:`needs_types` for this. -.. _service_github_custom: +.. _`service_github_custom`: Custom service -------------- + The preconfigured services ``github_issues``, ``github_prs`` and ``github_commits`` support the cloud instance of GitHub by default. @@ -206,29 +209,29 @@ Please see the this example for a ``Github Enterprise`` configuration in your ** .. code-block:: python - from sphinx_needs.services.github import GithubService - - needs_services = { - # Cloud GitHub configuration - 'github-issues': { - 'max_content_lines': 20, - 'id_prefix': 'GH_ISSUE_', - }, - # GitHub Enterprise configuration - 'my-company-issues': { - 'class': GithubService, - 'class_init': { - 'gh_type': 'issue' - }, - 'url': 'https://github.my-company.com/api/v3/', - 'username': 'my_username', - 'token': 'my_github_token', - 'download_avatars': True, - 'download_folder': 'company-avatars', - 'max_content_lines': 20, - 'id_prefix': 'COMPANY_ISSUE_', - } - } + from sphinx_needs.services.github import GithubService + + needs_services = { + # Cloud GitHub configuration + 'github-issues': { + 'max_content_lines': 20, + 'id_prefix': 'GH_ISSUE_', + }, + # GitHub Enterprise configuration + 'my-company-issues': { + 'class': GithubService, + 'class_init': { + 'gh_type': 'issue' + }, + 'url': 'https://github.my-company.com/api/v3/', + 'username': 'my_username', + 'token': 'my_github_token', + 'download_avatars': True, + 'download_folder': 'company-avatars', + 'max_content_lines': 20, + 'id_prefix': 'COMPANY_ISSUE_', + } + } ``class`` needs to reference the service-class object and ``class_init`` contains service specific initialisation options. In this case you must tell the generic ``GitHubService`` class which kind of information @@ -237,7 +240,6 @@ it shall deal with. Allowed are ``issue``, ``pr`` and ``commit``. All other options are normal configuration options for the service, which are also available for the GitHub cloud instance. - Examples -------- @@ -259,19 +261,19 @@ Document commit ``a4a596`` of **Sphinx-Needs**. .. code-block:: rst - .. needservice:: github-commits - :specific: useblocks/sphinx-needs/a4a596 - + .. needservice:: github-commits + :specific: useblocks/sphinx-needs/a4a596 Filtering +++++++++ + Show all needs, which have ``github`` as part of their ``service`` value. .. code-block:: rst - .. needtable:: - :filter: 'github' in service - :columns: id, title, type, service, user + .. needtable:: + :filter: 'github' in service + :columns: id, title, type, service, user .. needtable:: :filter: 'github' in service diff --git a/docs/services/index.rst b/docs/services/index.rst index 3214734e1..02faf95be 100644 --- a/docs/services/index.rst +++ b/docs/services/index.rst @@ -2,6 +2,7 @@ Services ======== + .. versionadded:: 0.6.0 Services are used by **Sphinx-Needs** to get information from external services and create need objects based on this @@ -49,16 +50,17 @@ Configuration needs_services ++++++++++++++ + Stores all service related configuration options in a dictionary. .. code-block:: python - needs_services = { - 'service_name': { - "option_1": "value", - # ... - } - } + needs_services = { + 'service_name': { + "option_1": "value", + # ... + } + } Normally all services have a working default configuration and no extra configuration is needed for basic tasks. However, if a service needs specific options or custom tasks are needed @@ -69,6 +71,7 @@ For available configuration options please take a look into the related service needs_service_all_data ++++++++++++++++++++++ + If a service returns data for an option, which was not registered by the service itself or the user via :ref:`needs_extra_options`, this information is added to the content part. @@ -76,6 +79,7 @@ Set ``needs_service_all_data`` to ``False`` to hide this kind of information. Multiple service instances -------------------------- + Sometimes it makes sense to have multiple service instances, which provide the same functionality but need a different configuration, e.g. issues should be reported from GitHub cloud repositories and repositories from the company internal GitHub Enterprise instance. @@ -85,26 +89,26 @@ All you need to do is to set the Python service class, which must be mentioned u .. code-block:: python - from sphinx_needs.services.xy import NeededService + from sphinx_needs.services.xy import NeededService - needs_services = { - 'my-company-service': { - 'class': NeededService, - 'class_init': { - # ... - }, - # ... - } - } + needs_services = { + 'my-company-service': { + 'class': NeededService, + 'class_init': { + # ... + }, + # ... + } + } Some services may need special configuration options to be initialised, these configs must be provided inside ``class_init``. For a complex example please of the GitHub service please take a look into its chapter :ref:`service_github_custom`. - Own services ------------ + A custom service can be created by providing your own service-class, which must inherit from the ``BaseService`` class and provide a function called ``request``. @@ -115,70 +119,70 @@ Example of a basic service: .. code-block:: python - from sphinx_needs.services.base import BaseService + from sphinx_needs.services.base import BaseService - class MyService(BaseService): + class MyService(BaseService): - def __init__(self, app, name, config, **kwargs): - # Get a config value from service related part - # of needs_services inside conf.py - self.my_config = config.get('my_config', 'DEFAULT') + def __init__(self, app, name, config, **kwargs): + # Get a config value from service related part + # of needs_services inside conf.py + self.my_config = config.get('my_config', 'DEFAULT') - # Custom init config, which is provided only once - # during class initialisation - custom_init = kwargs.get('custom_init', False) + # Custom init config, which is provided only once + # during class initialisation + custom_init = kwargs.get('custom_init', False) - super(GithubService, self).__init__() + super(GithubService, self).__init__() - def request(self, options): - # Get an option provided by the user in the directive call - status = options.get('status', 'Unknown') + def request(self, options): + # Get an option provided by the user in the directive call + status = options.get('status', 'Unknown') - data = [ - { - 'title': 'My Issue 1', - 'status': status, - 'my_config': self.my_config - }, - { - 'title': 'My Issue 2', - 'type': 'spec' - } - ] + data = [ + { + 'title': 'My Issue 1', + 'status': status, + 'my_config': self.my_config + }, + { + 'title': 'My Issue 2', + 'type': 'spec' + } + ] - return data + return data - def debug(self, options): - # Allows to send back data, which may be helpful for debugging. - # debug_data needs do be serializable via json.dump.() - debug_data = {'custom_debug': 'data'} - return debug_data + def debug(self, options): + # Allows to send back data, which may be helpful for debugging. + # debug_data needs do be serializable via json.dump.() + debug_data = {'custom_debug': 'data'} + return debug_data **Configuration inside conf.py**: .. code-block:: python - from somewhere.my_services import MyService + from somewhere.my_services import MyService - needs_services = { - 'my-service': { - 'class': MyService, - 'class_init': { - 'custom_init': True, - }, - 'my_config': 'Awesome', - } - } + needs_services = { + 'my-service': { + 'class': MyService, + 'class_init': { + 'custom_init': True, + }, + 'my_config': 'Awesome', + } + } **Using inside rst files**: .. code-block:: rst - .. needservice:: my-service - :status: open + .. needservice:: my-service + :status: open - .. needservice:: my-service - :debug: + .. needservice:: my-service + :debug: This would create 2 need objects with titles ``My Issue 1`` and ``My Issue 2``. @@ -186,8 +190,8 @@ To get the debug output of the service, use the ``debug`` flag: .. code-block:: rst - .. needservice:: my-service - :debug: + .. needservice:: my-service + :debug: Sphinx-Needs uses the extension `Sphinx-Data-Viewer `_ to represent the debug data in a nice and structured way. diff --git a/docs/services/open_needs.rst b/docs/services/open_needs.rst index f79a0e3cf..48bd0bca3 100644 --- a/docs/services/open_needs.rst +++ b/docs/services/open_needs.rst @@ -1,6 +1,4 @@ -.. _open_needs_service: - - +.. _`open_needs_service`: Open-Needs services =================== @@ -22,16 +20,19 @@ Example of an imported open-needs: Options ------- + The following options can be specified under ``.. needservice:: open-needs`` directive. prefix ###### + A string, which is taken as prefix for the need-id. E.g. ``ONS_IMPORT_`` –> ``ONS_IMPORT_003``. **Default value**: ``ONS_NEEDS_`` params ###### + A query string used to filter and organize the data retrieved from the ``open-needs`` service. For example: The query string ``limit=10`` can be used as: @@ -47,6 +48,7 @@ Example: ``:params: skip=1;limit=10`` url ### + URL of the server. The final ``RESTful API`` address endpoint(`url_postfix <#url_postfix>`_) gets added automatically. E.g.: ``http://127.0.0.1:9595`` or ``https://open-needs.org/`` @@ -54,16 +56,19 @@ E.g.: ``http://127.0.0.1:9595`` or ``https://open-needs.org/`` url_postfix ########### + The final address of the endpoint. E.g.: ``/api/needs/`` **Default value**: ``/api/needs/`` max_content_lines ################# + Maximum amount of lines from open-needs objects description/content to be used in need content. Config ------ + Most configuration needs to be done via the :ref:`needs_services` configuration in your **conf.py** file. :ref:`needs_services` must contain a key with the service name, E.g. ``open-needs`` @@ -72,29 +77,34 @@ The following key-value configuration parameters can be set for the Open-Need se url ### + Open-Needs service instance url. Default: ``https://api.open-need.com/`` username ######## + Username credentials used for login. password ######## + Password credentials used for login. id_prefix ######### + Prefix string for the final need id. mapping ####### + The field names of a service object do not often map to option names of Sphinx-Needs. So **mapping** defines where a Sphinx-Needs option shall get its value inside the service data. **mapping** must be a dictionary, where the key is the needs object name and the value is either a Jinja string such as ``is_{{status}}`` or a list/tuple, which defines the location of the value in the retrieved service data object. -.. _open_need_data: +.. _`open_need_data`: .. dropdown:: Example of an Open-Needs service data object @@ -125,7 +135,6 @@ or a list/tuple, which defines the location of the value in the retrieved servic }, ] - **Example using a Jinja string as value for the Open-Needs service** Goal: The need option ``author`` shall be set to the last and first names. @@ -135,12 +144,11 @@ under ``lastname`` and ``firstname``. The **mapping** entry for ``author`` would like this: - .. code-block:: python - 'mapping': { - 'author': "{{options.lastname}} {{options.firstname}}", - } + 'mapping': { + 'author': "{{options.lastname}} {{options.firstname}}", + } .. note:: @@ -156,17 +164,19 @@ The **mapping** entry for ``author`` would like this: .. code-block:: python - 'mapping': { - 'author': ["options", "lastname"], - } + 'mapping': { + 'author': ["options", "lastname"], + } content ####### + Content takes a string, which gets interpreted as rst-code for the need-content area. Jinja support is also available, so that service data is available and can be accessed like ``{{data.description}}``. mappings_replaces ################# + There are use cases, where a value inside service data is not valid for a Sphinx-Needs options. For instance: In the data retrieved from the Open-Needs server, ``type`` is named ``Requirement``, but Sphinx-Needs supports only ``req`` as value for type option. @@ -174,6 +184,7 @@ For instance: In the data retrieved from the Open-Needs server, ``type`` is name extra_data ########## + There may be information stored inside the :ref:`Open-Needs ` service data fields which cannot be mapped to the Sphinx-Needs options, but is available inside the Need object. @@ -181,7 +192,6 @@ This can be done by using ``extra_data``, which adds this kind of information to The logic and syntax is the same as used by `mapping <#mapping>`_. - .. note:: Some options can be overwritten by setting them directly in the need service directive: @@ -199,10 +209,9 @@ The logic and syntax is the same as used by `mapping <#mapping>`_. :language: python :lines: 329-346 - - Examples -------- + **Code** .. code-block:: rst @@ -216,9 +225,7 @@ Examples **Result** -.. hint:: - - The below examples are just images, as no Open-Needs Server instance was available during documentation build. +.. hint:: The below examples are just images, as no Open-Needs Server instance was available during documentation build. .. image:: /_images/ons_example.png :align: center diff --git a/docs/support.rst b/docs/support.rst index d50efbb4a..14b00a437 100644 --- a/docs/support.rst +++ b/docs/support.rst @@ -10,6 +10,7 @@ We are happy for each new entry and support wherever we can. Professional Support -------------------- + If you need professional support you should get in contact with our company `useblocks `_. We are a bunch of passionated developers, who normally work on process, tool or embedded related projects for automotive diff --git a/docs/tutorial.rst b/docs/tutorial.rst index 601068724..460a8d10d 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -7,19 +7,18 @@ In this tutorial, we will demonstrate the use of sphinx-needs to build up a simp We will create need items, link them together, visualize the relationships between them, and generate traceability reports. .. needflow:: Engineering plan to develop a car - :alt: Engineering plan to develop a car - :root_id: T_CAR - :config: tutorial - :show_link_names: - :border_color: - [status == 'open']:FF0000, - [status == 'in progress']:0000FF, - [status == 'closed']:00FF00 + :alt: Engineering plan to develop a car + :root_id: T_CAR + :config: tutorial + :show_link_names: + :border_color: [status == 'open']:FF0000, + [status == 'in progress']:0000FF, + [status == 'closed']:00FF00 .. admonition:: Prerequisites - This tutorial assumes that you have already :ref:`installed sphinx-needs `, - and that you have a basic understanding of how to use :external+sphinx:doc:`Sphinx ` and :external+sphinx:ref:`reStructuredText `. + This tutorial assumes that you have already :ref:`installed sphinx-needs `, + and that you have a basic understanding of how to use :external+sphinx:doc:`Sphinx ` and :external+sphinx:ref:`reStructuredText `. Need Lifecycle -------------- @@ -51,50 +50,50 @@ sphinx-needs comes with some default types: ``req``, ``spec``, ``impl``, and ``t .. need-example:: A basic need item - .. req:: Basic need example - :id: basic_example + .. req:: Basic need example + :id: basic_example - A basic example of a need item. + A basic example of a need item. For our car though, we want to use custom types, to describe aspects of the process. This can be created in the ``conf.py`` file, using the :ref:`needs_types` configuration option: .. code-block:: python - needs_types = [ - { - "directive": "tutorial-project", - "title": "Project", - "prefix": "P_", # prefix for auto-generated IDs - "style": "rectangle", # style for the type in diagrams - "color": "#BFD8D2", # color for the type in diagrams - } - ] - -There are also some optional directive fields + needs_types = [ + { + "directive": "tutorial-project", + "title": "Project", + "prefix": "P_", # prefix for auto-generated IDs + "style": "rectangle", # style for the type in diagrams + "color": "#BFD8D2", # color for the type in diagrams + } + ] + +There are also some optional directive fields that can be used to add additional data to the item or further style its representation: .. need-example:: A custom need item - .. tutorial-project:: Our new car - :id: T_CAR - :tags: tutorial - :layout: clean_l - :image: _images/car.png - :collapse: true + .. tutorial-project:: Our new car + :id: T_CAR + :tags: tutorial + :layout: clean_l + :image: _images/car.png + :collapse: true - Presenting the β€œTeenTrek,” an autonomous driving car tailored for teenagers without a driving license. - Equipped with advanced AI navigation and safety protocols, it ensures effortless and secure transportation. - The interior boasts entertainment systems, study areas, and social hubs, catering to teen preferences. - The TeenTrek fosters independence while prioritizing safety and convenience for young passengers. + Presenting the β€œTeenTrek,” an autonomous driving car tailored for teenagers without a driving license. + Equipped with advanced AI navigation and safety protocols, it ensures effortless and secure transportation. + The interior boasts entertainment systems, study areas, and social hubs, catering to teen preferences. + The TeenTrek fosters independence while prioritizing safety and convenience for young passengers. .. seealso:: - - For full options see the reference sections for :ref:`needs_types configuration ` and :ref:`need items directive `. - To add additional fields to the directive, - see :ref:`needs_extra_options`, - and to set default values see :ref:`needs_global_options`. + For full options see the reference sections for :ref:`needs_types configuration ` and :ref:`need items directive `. + + To add additional fields to the directive, + see :ref:`needs_extra_options`, + and to set default values see :ref:`needs_global_options`. Enforcing valid need items .......................... @@ -106,7 +105,6 @@ you can configure :ref:`needs_statuses`, :ref:`needs_tags` or :ref:`needs_warnin These will emit warnings when building the documentation if the values are not as expected. - Referring to a need item ------------------------ @@ -114,12 +112,11 @@ We can refer to the needs we create in the text using the :ref:`need role `. + The project is described in more detail in :need:`[[title]] `. We shall also see later how to create tables and other visualizations of multiple items. @@ -133,14 +130,14 @@ We can define custom link types in the ``conf.py`` file, using the :ref:`needs_e .. code-block:: python - needs_extra_links = [ - { - "option": "tutorial_required_by", - "incoming": "requires", # text to describe incoming links - "outgoing": "required by", # text to describe outgoing links - "style": "#00AA00", # color for the link in diagrams - }, - ] + needs_extra_links = [ + { + "option": "tutorial_required_by", + "incoming": "requires", # text to describe incoming links + "outgoing": "required by", # text to describe outgoing links + "style": "#00AA00", # color for the link in diagrams + }, + ] We can now uses these links when specifying need items, notice how "back links" are automatically generated when displaying the item: @@ -157,7 +154,7 @@ We can now uses these links when specifying need items, notice how "back links" :id: T_CONNECT :tags: tutorial :tutorial_required_by: T_CAR - + The car should be equipped with built-in Wi-Fi, Bluetooth connectivity, and compatibility with smartphone integration systems to enable seamless communication and entertainment for teenagers on the go. Lets also add some more need items to our plan: @@ -171,15 +168,14 @@ Lets also add some more need items to our plan: :tags: tutorial :tutorial_specifies: T_SAFE - The RADAR sensor software for the car must accurately detect and track surrounding objects - within a specified range. It should employ signal processing algorithms to filter out noise - nd interference, ensuring reliable object detection in various weather and road conditions. - The software should integrate seamlessly with the car's control system, providing real-time - data on detected objects to enable collision avoidance and adaptive cruise control functionalities. - Additionally, it should adhere to industry standards for safety and reliability, with robust + The RADAR sensor software for the car must accurately detect and track surrounding objects + within a specified range. It should employ signal processing algorithms to filter out noise + nd interference, ensuring reliable object detection in various weather and road conditions. + The software should integrate seamlessly with the car's control system, providing real-time + data on detected objects to enable collision avoidance and adaptive cruise control functionalities. + Additionally, it should adhere to industry standards for safety and reliability, with robust error handling mechanisms in place. - .. tutorial-spec:: Implement distant detection :id: T_DIST :tags: tutorial @@ -187,9 +183,7 @@ Lets also add some more need items to our plan: Software Specification for Distance Detection Algorithm. -.. seealso:: - - For full options see the reference sections for :ref:`need_extra_links configuration ` and :ref:`need items directive `. +.. seealso:: For full options see the reference sections for :ref:`need_extra_links configuration ` and :ref:`need items directive `. Importing need items -------------------- @@ -201,13 +195,11 @@ Lets import some test cases, we add an additional tag to each, to make them easi .. need-example:: Importing need items - .. needimport:: _static/tutorial_needs.json - :tags: tutorial,tutorial_tests - :collapse: true + .. needimport:: _static/tutorial_needs.json + :tags: tutorial,tutorial_tests + :collapse: true -.. seealso:: - - For full options see the reference sections for :ref:`needimport directive ` and :ref:`needservice directive `. +.. seealso:: For full options see the reference sections for :ref:`needimport directive ` and :ref:`needservice directive `. Modifying need items -------------------- @@ -222,24 +214,22 @@ Here we filter by the tag we set on the imported items above: .. need-example:: Extending need items - .. needextend:: "tutorial_tests" in tags - :+tutorial_tests: T_RADAR - :status: open + .. needextend:: "tutorial_tests" in tags + :+tutorial_tests: T_RADAR + :status: open - .. needextend:: T_001 - :status: closed + .. needextend:: T_001 + :status: closed - .. needextend:: T_002 - :status: in progress + .. needextend:: T_002 + :status: in progress -.. note:: +.. note:: - The ``needextend`` does not have any visible output, - but it you look at the items, they will now have the additional link and status fields. + The ``needextend`` does not have any visible output, + but it you look at the items, they will now have the additional link and status fields. -.. seealso:: - - For full options see the reference sections for :ref:`needextend directive `. +.. seealso:: For full options see the reference sections for :ref:`needextend directive `. Summarising needs ----------------- @@ -261,62 +251,60 @@ sorted by ID, and showing the status of each item: .. need-example:: Simple list - .. needlist:: - :tags: tutorial - :sort_by: id - :show_status: + .. needlist:: + :tags: tutorial + :sort_by: id + :show_status: Similarly, we can display the same items in a table format: .. need-example:: Simple table - .. needtable:: - :tags: tutorial - :sort: id - :columns: id,type,title,status - :style: table + .. needtable:: + :tags: tutorial + :sort: id + :columns: id,type,title,status + :style: table There are currently two styles for the table; a simple HTML ``table``, or the default ``datatables`` style to add dynamic pagination, filtering and sorting, using the `DataTables `__ JS package: .. need-example:: Table with dynamic features - .. needtable:: - :tags: tutorial - :sort: id - :columns: id,type,title,status - :style: datatable + .. needtable:: + :tags: tutorial + :sort: id + :columns: id,type,title,status + :style: datatable Finally, we can display a :ref:`flow diagram ` of the need items, to also show the relationships between them: - + .. need-example:: Flow diagram - .. needflow:: Engineering plan to develop a car - :alt: Engineering plan to develop a car - :root_id: T_CAR - :config: lefttoright,tutorial - :show_link_names: - :border_color: - [status == 'open']:FF0000, - [status == 'in progress']:0000FF, - [status == 'closed']:00FF00 + .. needflow:: Engineering plan to develop a car + :alt: Engineering plan to develop a car + :root_id: T_CAR + :config: lefttoright,tutorial + :show_link_names: + :border_color: [status == 'open']:FF0000, + [status == 'in progress']:0000FF, + [status == 'closed']:00FF00 .. dropdown:: Aternative use of Graphviz engine - You can also use the Graphviz engine to render the flow diagram, by setting the ``engine`` option to ``graphviz``: + You can also use the Graphviz engine to render the flow diagram, by setting the ``engine`` option to ``graphviz``: - .. need-example:: Flow diagram with Graphviz + .. need-example:: Flow diagram with Graphviz - .. needflow:: Engineering plan to develop a car - :engine: graphviz - :alt: Engineering plan to develop a car - :root_id: T_CAR - :config: lefttoright,tutorial - :show_link_names: - :border_color: - [status == 'open']:FF0000, - [status == 'in progress']:0000FF, - [status == 'closed']:00FF00 + .. needflow:: Engineering plan to develop a car + :engine: graphviz + :alt: Engineering plan to develop a car + :root_id: T_CAR + :config: lefttoright,tutorial + :show_link_names: + :border_color: [status == 'open']:FF0000, + [status == 'in progress']:0000FF, + [status == 'closed']:00FF00 Analysing Metrics ----------------- @@ -331,9 +319,9 @@ In the following examples we will display metrics of the test cases we imported .. need-example:: Count of need items - - Open: :need_count:`'tutorial_tests' in tags and status == 'open'` - - In Progress: :need_count:`'tutorial_tests' in tags and status == 'in progress'` - - Closed: :need_count:`'tutorial_tests' in tags and status == 'closed'` + - Open: :need_count:`'tutorial_tests' in tags and status == 'open'` + - In Progress: :need_count:`'tutorial_tests' in tags and status == 'in progress'` + - Closed: :need_count:`'tutorial_tests' in tags and status == 'closed'` .. need-example:: Pie chart of metric @@ -370,8 +358,7 @@ Also, see :ref:`other extensions ` offered by `useblocks