diff --git a/docs/api.rst b/docs/api.rst index 7332cebb2..e4885ec2f 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -3,12 +3,12 @@ Python API ========== -**Sphinx-Needs** provides an open API for other Sphinx-extensions to provide specific need-types, create needs or -make usage of the filter possibilities. +**Sphinx-Needs** provides an open API for other Sphinx-extensions to provide specific need-types, create needs, or +make use of the filter possibilities. The API allows the injection of extra configuration, but -does not support manipulation of it (e.g remove need types), -to keep the final configuration transparent for the Sphinx project authors. +does not support manipulation of it (e.g., removing need types), +in order to keep the final configuration transparent for Sphinx project authors. .. _api_configuration: diff --git a/docs/builders.rst b/docs/builders.rst index 06850967b..3b07d64a6 100644 --- a/docs/builders.rst +++ b/docs/builders.rst @@ -44,7 +44,7 @@ Format ++++++ As well as the ``filters`` and ``needs`` data, the **needs.json** file also contains the ``needs_schema``. -This is a JSON schema of for the data structure of a single need, +This is a JSON schema for the data structure of a single need, and also includes a ``field_type`` for each field, to denote the source of the field, that can be one of: ``core``, ``links``, ``backlinks``, ``extra``, ``global``. @@ -187,9 +187,9 @@ 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. +The **needs_id** builder exports all found needs and selected filter results to a set of JSON files for each need, with the filename being the ``id`` of the need. -The build creates a folder called :ref:``needs_build_json_per_id_path`` and all file json of each need inside the given build-folder. +The build creates a folder called :ref:``needs_build_json_per_id_path`` and stores all JSON files for each need inside the given build-folder. Usage +++++ diff --git a/docs/configuration.rst b/docs/configuration.rst index 6854798eb..0e0b6bde6 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -176,7 +176,7 @@ By default it is set to: .. note:: - `color` can also be an empty string. This makes sense, if the PlantUMl configuration is mostly provided by using + `color` can also be an empty string. This makes sense, if the PlantUML configuration is mostly provided by using :ref:`needs_flow_configs` and the used colors shall not get overwritten by type specific values. .. warning:: @@ -435,7 +435,7 @@ Each configured link should define: * **allow_dead_links** (optional): True/False. If True, dead links are allowed and do not throw a warning. See :ref:`allow_dead_links` for details. Default: False. * **style** (optional): A plantuml style description, e.g. "#FFCC00". Used for :ref:`needflow`. See :ref:`links_style`. -* **style_part** (optional): Same as **style**, but get used if link is connected to a :ref:`need_part`. +* **style_part** (optional): Same as **style**, but gets used if link is connected to a :ref:`need_part`. See :ref:`links_style`. Configuration example: @@ -473,11 +473,11 @@ The above example configuration allows the following usage: :checks: EXTRA_REQ_001, DEAD_LINK_NOT_ALLOWED :triggers: DEAD_LINK -.. attention:: The used option name can not be reused in the configuration of :ref:`needs_global_options`. +.. attention:: The used option name cannot be reused in the configuration of :ref:`needs_global_options`. Link types with option-name **links** and **parent_needs** are added by default. You are free to overwrite the default config by defining your own type with option name **links** or **parent_needs**. -This type will be used as default configuration for all links. +This type will be used as the default configuration for all links. .. _`allow_dead_links`: @@ -574,7 +574,7 @@ Use ``style_start`` and ``style_end`` like this: .. note:: Some plantuml diagrams have restrictions in the order of color (`style`) - and orientation (`left`, `rigth`, `up` and `down`). We suggest to set the orientation + and orientation (`left`, `right`, `up` and `down`). We suggest to set the orientation in `style_end` like in the example above, as this is more often supported. .. _`needs_filter_data`: @@ -596,8 +596,8 @@ Configuration example: "sphinx_tag": custom_defined_func(), } -The defined ``needs_filter_data`` must be a dictionary. Its values can be a string variable or a custom defined -function. The function get executed during config loading and must return a string. +The defined ``needs_filter_data`` must be a dictionary. Its values can be a string variable or a custom-defined +function. The function gets executed during config loading and must return a string. The value of ``needs_filter_data`` will be available as data inside :ref:`filter_string` and can be very powerful together with internal needs information to filter needs. @@ -639,7 +639,7 @@ Fields can be added or existing fields can even be manipulated. .. note:: Keep in mind this only affects the filter results, original needs as displayed somewhere else are not modified. -If set to False, the filter results contains the original need fields and any manipulations of need fields are lost. +If set to False, the filter results contain the original need fields and any manipulations of need fields are lost. .. code-block:: python @@ -682,7 +682,7 @@ needs_flow_show_links .. versionadded:: 0.3.11 -Used to de/activate the output of link type names beside the connection in the :ref:`needflow` directive: +Used to activate/deactivate the output of link type names beside the connection in the :ref:`needflow` directive: .. code-block:: python @@ -1754,7 +1754,7 @@ Allows to reference and use external needs without having their representation i }, ] -``needs_external_needs`` must be a list of dictionary elements and each dictionary must/can have the following +``needs_external_needs`` must be a list of dictionary elements and each dictionary can/must have the following keys: :base_url: Base url which is used to calculate the final, specific need url. Normally the path under which the ``index.html`` is provided. @@ -1764,14 +1764,14 @@ keys: If not, the external need url uses the default calculated ``base_url``. |br| The ``target_url`` supports Jinja context ``{{need[]}}``, ``need option`` used as key, e.g ``{{need['id']}}`` or ``{{need['type']}}``. :json_url: An url, which can be used to download the ``needs.json`` (or similar) file. -:json_path: The path to a ``needs.json`` file located inside your documentation project. Can not be used together with - ``json_url``. |br| The value must be a relative path, which is relative to the project configuration folder +:json_path: The path to a ``needs.json`` file located inside your documentation project. Cannot be used together with + ``json_url``. |br| The value must be a relative path, relative to the project configuration folder (where the **conf.py** is stored). (Since version `0.7.1`) :version: Defines the version to use inside the ``needs.json`` file (*optional*). :id_prefix: Prefix as string, which will be added to all id of external needs. Needed, if there is the risk that needs from different projects may have the same id (*optional*). :css_class: A class name as string, which gets set in link representations like :ref:`needtable`. - The related CSS class definition must be done by the user, e.g. by :ref:`own_css`. + The related CSS class definition must be provided by the user, e.g., by :ref:`own_css`. (*optional*) (*default*: ``external_link``) .. _`needs_needextend_strict`: @@ -1964,7 +1964,7 @@ Example: needs_build_json_per_id = False -.. hint:: The created single json file per need, located in :ref:`needs_build_json_per_id_path` folder, e.g ``_build/needs_id/abc_432.json`` +.. hint:: The created single json file per need is located in the :ref:`needs_build_json_per_id_path` folder, e.g., ``_build/needs_id/abc_432.json`` .. _`needs_build_json_per_id_path`: @@ -1983,7 +1983,7 @@ Example: needs_build_json_per_id_path = "needs_id" -.. hint:: The created ``needs_id`` folder gets stored in the ``outdir`` of the current builder. The final location is e.g. ``_build/needs_id`` +.. hint:: The created ``needs_id`` folder is stored in the ``outdir`` of the current builder. The final location is, e.g., ``_build/needs_id`` .. _`needs_build_needumls`: @@ -1995,7 +1995,7 @@ Exports :ref:`needuml` data during each build. This option works like :ref:`needs_build_json`. But the value of :ref:`needs_build_needumls` should be a string, not a boolean. Default value of is: ``""``. -This value of this option shall be a **relative folder path**, which specifies and creates the relative folder in the +The value of this option must be a **relative folder path**, which specifies and creates the relative folder in the ``outdir`` of the current builder. Example: @@ -2268,15 +2268,15 @@ Configuration example: } The``needs_render_context`` configuration option must be a dictionary. -The dictionary consists of key-value pairs where the key is a string used as reference to the value. -The value can be any data type (string, integer, list, dict, etc.) +The dictionary consists of key-value pairs where the key is a string used as a reference to the value. +The value can be any data type (string, integer, list, dict, etc.). .. warning:: - The value can also be a custom defined function, + The value can also be a custom-defined function, however, this will deactivate the caching and incremental build feature of Sphinx. -The data passed via needs_render_context will be available as variable(s) when rendering Jinja templates or strings. +The data passed via needs_render_context will be available as variables when rendering Jinja templates or strings. You can use the data passed via needs_render_context as shown below: .. need-example:: @@ -2511,4 +2511,4 @@ final need and schema looks like. .. note:: For large need counts, the debug output can become very large. - Writing debug output also affects the validation performance negatively. + Writing debug output also negatively affects validation performance. diff --git a/docs/contributing.rst b/docs/contributing.rst index b500bf35d..0cf8990df 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -108,13 +108,13 @@ Running JS Testcases with PyTest **Setup Cypress Locally** * Install Node JS on your computer and ensure it can be accessed through the CMD. -* Install Cypress using the npm package manager by running ``npm install cypress``. Visit this link for more information on `how to install Cypress `_. -* Verify if Cypress is installed correctly and is executable by running: ``npx cypress verify``. Get out this page for more information about `Cypress commandline `_. -* If everything is successful then we can use Cypress. +* Install Cypress using the npm package manager by running ``npm install cypress``. See this link for more information on `how to install Cypress `_. +* Verify if Cypress is installed correctly and is executable by running: ``npx cypress verify``. See this page for more information about `Cypress commandline `_. +* If everything is successful, you can use Cypress. **Enable Cypress Test in Python Test Files** -Under the ``js_test`` folder, you can save your Cypress JS test files (files should end with: ``*.cy.js``). For each Cypress JS test file, you will need to write the Cypress JS test cases in the file. You can read more from the `Cypress Docs `_. You can also check the ``tests/js_test/sn-collapse-button.cy.js`` file as reference. +Under the ``js_test`` folder, you can save your Cypress JS test files (files should end with ``*.cy.js``). For each Cypress JS test file, you will need to write the Cypress JS test cases in the file. You can read more from the `Cypress Docs `_. You can also check the ``tests/js_test/sn-collapse-button.cy.js`` file as reference. In your Python test files, you must mark every JS related test case with the marker - ``jstest`` and you must include the ``spec_pattern`` key-value pair as part of the ``test_app`` fixture parameter. Also, you need to pass the ``test_server`` fixture to your test function for it to use the automated HTTP test server. For example, your test case could look like this: @@ -169,7 +169,7 @@ After you set the ``spec_pattern`` key-value pair as part of the ``test_app`` fi 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.""" + """Check whether the Sphinx-Needs collapse button works in the provided documentation source.""" app = test_app app.build() @@ -189,7 +189,7 @@ After you set the ``spec_pattern`` key-value pair as part of the ``test_app`` fi return { "returncode": 0, "stdout": "Test passed string", - "stderr": "Errors encountered, + "stderr": "Errors encountered", } You can run the ``make test-js`` command to check all JS testcases. @@ -197,7 +197,7 @@ 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. + Please check your system's monitoring app to end the process if it is not terminated automatically. Benchmarks ---------- @@ -205,20 +205,19 @@ Benchmarks **Sphinx-Needs** own documentation is used for creating a benchmark for each PR. If the runtime takes 10% longer as the previous ones, the benchmark test will fail. -Benchmark test cases are available under ``tests/benchmarks``. +Benchmark test cases are available in ``tests/benchmarks``. The results for each PR/commit get added to a chart, which is available under http://useblocks.com/sphinx-needs/bench/index.html. -The benchmark data is stored on the `benchmarks` branch, which is also used by github-pages as -source. +The benchmark data is stored on the `benchmarks` branch, which is also used by GitHub Pages as its 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. -The tag must follow the format: ``[0-9].[0-9]+.[0-9]``. Otherwise the release jobs won't trigger. +This is triggered automatically if a tag is created and pushed. +The tag must follow the format ``[0-9].[0-9]+.[0-9]``. Otherwise, the release jobs will not trigger. The release jobs will build the source and wheel distribution and try to upload them. @@ -250,7 +249,7 @@ The following is an outline of the build events which this extension adds to the #. For changed documents (``doctree-read`` event, priority 880 of transforms) - - Determine and add data on parent sections and needs(``analyse_need_locations``) + - Determine and add data on parent sections and needs (``analyse_need_locations``) - Remove ``Need`` nodes marked as ``hidden`` (``analyse_need_locations``) #. When building in parallel mode (``env-merge-info`` event), merge ``BuildEnvironment`` data (``merge_data``) @@ -266,23 +265,23 @@ The following is an outline of the build events which this extension adds to the #. For all changed documents, or their dependants (``doctree-resolved``) - Replace all ``Needextract`` nodes with a list of the collected ``Need`` (``process_creator``) - - Remove all ``Need`` nodes, if ``needs_include_needs`` is ``True`` (``process_need_nodes``) - - Call dynamic functions, set as values on the need data items and replace them with their return values (``process_need_nodes -> resolve_dynamic_values``) - - Replace needs data variant values (``process_need_nodes -> resolve_variants_options``) + - Remove all ``Need`` nodes if ``needs_include_needs`` is ``True`` (``process_need_nodes``) + - Call dynamic functions set as values on the need data items and replace them with their return values (``process_need_nodes -> resolve_dynamic_values``) + - Replace need data variant values (``process_need_nodes -> resolve_variants_options``) - Check for dead links (``process_need_nodes -> check_links``) - Generate back links (``process_need_nodes -> create_back_links``) - - Process constraints, for each ``Need`` node (``process_need_nodes -> process_constraints``) - - Perform all modifications on need data items, due to ``Needextend`` nodes (``process_need_nodes -> extend_needs_data``) - - Format each ``Need`` node to give the desired visual output (``process_need_nodes -> print_need_nodes``) - - Process all other need specific nodes, replacing them with the desired visual output (``process_creator``) + - Process constraints for each ``Need`` node (``process_need_nodes -> process_constraints``) + - Perform all modifications on need data items due to ``Needextend`` nodes (``process_need_nodes -> extend_needs_data``) + - Format each ``Need`` node to produce the desired visual output (``process_need_nodes -> print_need_nodes``) + - Process all other need-specific nodes, replacing them with the desired visual output (``process_creator``) #. At the end of the build (``build-finished`` event) - - Call all user defined need data checks, a.k.a `needs_warnings` (``process_warnings``) - - Write the ``needs.json`` to the output folder, if `needs_build_json = True` (``build_needs_json``) - - Write the ``needs.json`` per ID to the output folder, if `needs_build_json_per_id = True` (``build_needs_id_json``) - - Write all UML files to the output folder, if `needs_build_needumls = True` (``build_needumls_pumls``) - - Print process timing, if `needs_debug_measurement = True` (``process_timing``) + - Call all user-defined need data checks, a.k.a. `needs_warnings` (``process_warnings``) + - Write the ``needs.json`` to the output folder if `needs_build_json = True` (``build_needs_json``) + - Write the ``needs.json`` per ID to the output folder if `needs_build_json_per_id = True` (``build_needs_id_json``) + - Write all UML files to the output folder if `needs_build_needumls = True` (``build_needumls_pumls``) + - 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 924a3182a..2e715a04c 100644 --- a/docs/directives/list2need.rst +++ b/docs/directives/list2need.rst @@ -5,7 +5,7 @@ list2need .. versionadded:: 1.2.0 -``list2need`` allows to create need objects out ouf a given list, where each list entry is used to create +``list2need`` allows to create need objects out of a given list, where each list entry is used to create a single need. It allows to speed up the need-creation process for simple needs, which in most cases just have a title @@ -64,7 +64,7 @@ The used list structure was defined to be as small as possible. Each line starting with a ``*`` will create a new need object. -To define a child-need, add **2 additional whitespaces** infront of ``*``. +To define a child-need, add **2 additional whitespaces** in front of ``*``. This is called the indentation level and each level must have a need-type defined in the ``types`` option. A line starting **without** a ``*`` will be added to the prior one. @@ -288,7 +288,7 @@ Lists with need-part support Second: :np:`(ANOTHER)ANOTHER need-part` * And a spec need. - Lets reference a need-part frm above: :need:`LIST2NEED-REQ-1.1` + Let's reference a need-part from above: :need:`LIST2NEED-REQ-1.1` .. list2need:: :types: req, spec @@ -301,7 +301,7 @@ Lists with need-part support Second: :np:`(ANOTHER)ANOTHER need-part` * And a spec need. - Lets reference a need-part frm above: :need:`LIST2NEED-REQ-1.1` + Let's reference a need-part from above: :need:`LIST2NEED-REQ-1.1` .. _list2need_meta_data: diff --git a/docs/directives/need.rst b/docs/directives/need.rst index 81a6899ab..a5db2e383 100644 --- a/docs/directives/need.rst +++ b/docs/directives/need.rst @@ -14,7 +14,7 @@ You can define the type using the correct directive, like ``.. req::`` or ``.. t :tags: user;login :collapse: false - Our users needs to get logged in via our login forms on **/login.php**. + Our users need 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. @@ -33,7 +33,7 @@ Variants for options support .. versionadded:: 1.0.2 Needs variants add support for variants handling on need options. |br| -The support for variants options introduce new ideologies on how to set values for *need options*. +The support for variants options introduces new ideologies on how to set values for *need options*. To implement variants options, you can set a *need option* to a variant definition or multiple variant definitions. A variant definition can look like ``var_a:open`` or ``['name' in tags]:assigned``. @@ -46,7 +46,7 @@ and ``assigned`` is the value. Rules for specifying variant definitions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* Variants gets checked from left to right. +* Variants get checked from left to right. * When evaluating a variant definition, we use data from the current need object, `Sphinx-Tags `_, and :ref:`needs_filter_data` as the context for filtering. @@ -161,7 +161,7 @@ Below is an implementation of variants for need options: Diagram support --------------- -A need objects can also define it's own PlantUML representation. +A need object can also define its 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``. @@ -173,7 +173,7 @@ This diagram data can then be used in other :ref:`needuml` calls to combine and :id: SP_INT :status: open - This are the provided interfaces: + These are the provided interfaces: .. needuml:: @@ -198,8 +198,7 @@ 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. +The option ``arch`` can be easily used for filtering. For instance, to show all need objects which represent some kind of diagram. .. need-example:: @@ -220,7 +219,7 @@ The given ID must match the regular expression (regex) value for the :ref:`needs 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 -also include title if :ref:`needs_id_from_title` is set to **True**. +also include the 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: @@ -303,7 +302,7 @@ delete There is a **:delete:** option. If the value of the option is set to **True**, the need will be deleted completely from any NeedLists or NeedDicts including the ``needs.json`` file. -This option allows a user to have multiple need-objects with the same id, but only one is shown in the documentation. +This option allows a user to have multiple need objects with the same id, but only one is shown in the documentation. Allowed values (case-insensitive): @@ -524,7 +523,7 @@ style ``style`` can be used to set a specific class-attribute for the need representation. -The class-attribute can then be selected with **CSS** to specify the layout of the need. +The class attribute can then be selected with **CSS** to specify the layout of the need. .. need-example:: @@ -586,7 +585,7 @@ For example, if the filename is ``my_template.need``, you can reference it like You can specify the location of all template files by configuring the :ref:`needs_template_folder`, which is by default ``needs_templates/``, in the **conf.py** file. -You can have several templates, but can set only one for a need. +You can have several templates, but can set only one for each need. .. dropdown:: Template ``spec_template.need`` @@ -664,7 +663,7 @@ duration Track the duration of a need. -The need allows any value but the :ref:`needgantt` directive uses and interprets it as days by default. +The need allows any value, but the :ref:`needgantt` directive uses and interprets it as days by default. .. _need_completion: @@ -676,7 +675,7 @@ completion Track the completion of a need. -The need allows any value but the :ref:`needgantt` directive uses and interprets it as percentage by default. +The need allows any value, but the :ref:`needgantt` directive uses and interprets it as a percentage by default. Customized Options diff --git a/docs/directives/needarch.rst b/docs/directives/needarch.rst index aebe10da6..ac04a7a9c 100644 --- a/docs/directives/needarch.rst +++ b/docs/directives/needarch.rst @@ -5,8 +5,8 @@ needarch ======== -``needarch`` behaves exactly like :ref:`needuml`, but only works inside a need. It provides also additional exclusive -jinja functions :ref:`needarch_jinja_need` and :ref:`needarch_jinja_import`. +``needarch`` behaves exactly like :ref:`needuml`, but only works inside a need. It also provides additional exclusive +Jinja functions :ref:`needarch_jinja_need` and :ref:`needarch_jinja_import`. .. need-example:: @@ -60,7 +60,7 @@ The `need()` function provides you the need information the :ref:`needarch` is e import(need_links_option_name) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This function takes undefined amounts of current need links option names as arguments. +This function takes an arbitrary number of current need link option names as arguments. Then it executes :ref:`needuml_jinja_uml` automatically for all links/need_ids defined from the given arguments. @@ -97,9 +97,9 @@ NeedArch Loop Example .. versionadded:: 1.0.3 NeedArch can detect include loops `(uml('1') -> uml('2') -> uml('3') -> uml('1')` -and can avoid to include an element twice. Maybe this is not always the use case -you have, if so please create an issue and mention this chapter. The algorithm -does detect different parameter sets and does import `uml()` calls with different +and can avoid including an element twice. This may not always match your use case; if so, +please create an issue and mention this chapter. The algorithm +detects different parameter sets and imports `uml()` calls with different :ref:`parameter ` to the same need. .. need-example:: diff --git a/docs/directives/needbar.rst b/docs/directives/needbar.rst index e824d2390..4c29c2a06 100644 --- a/docs/directives/needbar.rst +++ b/docs/directives/needbar.rst @@ -16,8 +16,8 @@ needbar 15,10,20 20,15,10 -Each content value gets interpreted either as static float/int value or as a :ref:`filter_string`. -The amount of found needs by the filter string is then used as value. +Each content value is interpreted either as a static float/int value or as a :ref:`filter_string`. +The number of found needs by the filter string is then used as the value. .. note:: @@ -84,10 +84,10 @@ content ~~~~~~~ In the example below, we fetch the ``:xlabels:`` and ``:ylabels:`` options from the content using ``FROM_DATA`` with the `labels`_. -You can use white spaces to format the table to improve readability. +You can use white space to format the table to improve readability. From the content, we interpret each value either as a static float/int value or as a :ref:`filter_string`. -We get the bar chart's data (values) from the amount of **need** objects found by the filter string. +We get the bar chart's data (values) from the number of **need** objects found by the filter string. Below is a more realistic example with data fetched from filters, together with hardcoded data: @@ -144,10 +144,10 @@ labels ~~~~~~ | Use ``:xlabels:`` to set labels for columns of the data. -| Use ``:ylabels:`` to set labels for row of the data. +| Use ``:ylabels:`` to set labels for rows of the data. You can define the ``:xlabels:`` and/or ``:ylabels:`` by setting a comma separated string. -The amount of labels must match the amount of values/lines from content. |br| +The amount of labels must match the number 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:: @@ -182,7 +182,7 @@ Also, you can set the ``:xlabels:`` and/or ``:ylabels:`` value to ``FROM_DATA`` stacked ~~~~~~~ -You can render the barchart in a stacked design by setting ``:stacked:`` flag. +You can render the barchart in a stacked design by setting the ``:stacked:`` flag. The ``:stacked:`` flag does not support any values. @@ -199,9 +199,9 @@ The ``:stacked:`` flag does not support any values. show_sum ~~~~~~~~ -You can render the barchart with detailed information of the height of each bar by setting the ``:show_sum:`` flag. +You can render the barchart with detailed information about the height of each bar by setting the ``:show_sum:`` flag. -The ``:show_sum:`` flag does not support any values and it's useful with the ``stacked`` option enabled. +The ``:show_sum:`` flag does not support any values and is useful with the ``stacked`` option enabled. .. need-example:: @@ -226,9 +226,9 @@ The ``:show_sum:`` flag does not support any values and it's useful with the ``s show_top_sum ~~~~~~~~~~~~ -You can render the barchart with detailed information of the height of each bar above by setting the ``:show_top_sum:`` flag. +You can render the barchart with detailed information about the height of each bar above by setting the ``:show_top_sum:`` flag. -The ``:show_sum:`` flag does not support any values and it's useful with the ``stacked`` option enabled. +The ``:show_top_sum:`` flag does not support any values and is useful with the ``stacked`` option enabled. .. need-example:: @@ -255,7 +255,7 @@ horizontal You can render the bar chart with horizontal bars by setting the ``:horizontal:`` flag. -The ``:horizontal:`` flag does not support any values and it's useful with the ``stacked`` option enabled. +The ``:horizontal:`` flag does not support any values and is useful with the ``stacked`` option enabled. .. hint:: The meaning of `labels`_ will change automatically with the usage of ``:horizontal:``. We will use the @@ -289,13 +289,13 @@ transpose ~~~~~~~~~ You can `transpose `_ the data in the content by setting the ``:transpose:`` flag. -The idea is, you can try to see the data from different point of view, without refactoring. +The idea is that you can try to see the data from a different point of view, without refactoring. -The ``:transpose:`` flag does not support any values and it's useful with big content tables. +The ``:transpose:`` flag does not support any values and is useful with large 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. + * Remember that with the ``:transpose:`` flag, the length and height of the content data change, so do not think about the width of matching elements, like `colors`_. Please review the impact of ``:transpose:`` before using it. .. need-example:: @@ -325,9 +325,9 @@ The ``:transpose:`` flag does not support any values and it's useful with big co rotation ~~~~~~~~ -| Use ``:xlabels_rotation:`` to set rotation of labels for x-axis on the diagram. -| 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. +| Use ``:xlabels_rotation:`` to set the rotation of labels for the x-axis on the diagram. +| Use ``:ylabels_rotation:`` to set the rotation of labels for the y-axis on the diagram. +| Use ``:sum_rotation:`` to set the rotation of labels for bars on the diagram. .. need-example:: @@ -368,12 +368,12 @@ The ``:separator:`` is a string that supports any symbols. colors ~~~~~~ -``:colors:`` takes a comma separated list of color names and uses them for the bar charts. +``:colors:`` takes a comma-separated list of color names and uses them for the bar charts. See `Matplotlib documentation of supported colors `_ for a complete list of color names. -But besides names, ``:colors:`` options also supports hex-values like ``#ffcc00``. +But besides names, the ``:colors:`` option also supports hex-values like ``#ffcc00``. .. hint:: In a normal bar chart, we use the ``:colors:`` for the legend and bars itself. @@ -420,7 +420,7 @@ style It takes a string, which must match the `supported Matplotlib style names `_. -Useful styles are for example: +Useful styles are, for example: * default * classic diff --git a/docs/directives/needextend.rst b/docs/directives/needextend.rst index d8583acc2..b52211184 100644 --- a/docs/directives/needextend.rst +++ b/docs/directives/needextend.rst @@ -78,7 +78,8 @@ If you set the ``:strict:`` option value to ``true``, ``needextend`` raises an exception because the given ID does not exist, and the build stops. If you set the ``:strict:`` option value to ``false``, -``needextend`` logs an warning-level message in the console, and the build continues. + +``needextend`` logs a warning-level message in the console, and the build continues. Allowed values: @@ -136,20 +137,20 @@ Options containing links get handled in two steps: :id: extend_test_004 Had no links. - Got an incoming links ``extend_test_003`` and ``extend_test_006``. + Got incoming links ``extend_test_003`` and ``extend_test_006``. .. req:: needextend Example 5 :id: extend_test_005 :links: extend_test_003, extend_test_004 Had the two links: ``extend_test_003`` and ``extend_test_004``. - Both got deleted. + Both were deleted. .. req:: needextend Example 6 :id: extend_test_006 :links: extend_test_003 - Had the link ``extend_test_003``, got another one ``extend_test_004``. + Had the link ``extend_test_003``, and got another one ``extend_test_004``. .. needextend:: extend_test_003 :links: extend_test_004 @@ -169,7 +170,7 @@ Options containing links get handled in two steps: Monitoring modifications ------------------------ -All needs have this two internal parameters: +All needs have these two internal parameters: * ``is_modified``: A boolean value. Defaults to ``False`` * ``modifications``: A number. Defaults to ``0``. @@ -180,7 +181,7 @@ Also, the ``modifications`` number is increased by one. To see these values, use ``:layout: debug`` on the need or by :ref:`own_layouts`. -Also filtering for these values is supported: +Filtering for these values is also supported: .. need-example:: diff --git a/docs/directives/needextract.rst b/docs/directives/needextract.rst index 2b28e21ba..fc2734e52 100644 --- a/docs/directives/needextract.rst +++ b/docs/directives/needextract.rst @@ -32,7 +32,7 @@ For instance, a supplier could get a copy of requirements but would not see all ``needextract`` supports the full filtering possibilities of sphinx-needs. Please read :ref:`filter` for more information. -It also supports arguments as filter string, +It also supports arguments as a filter string, which works like the option `filter`, but also supports need ID as filter argument. @@ -42,7 +42,7 @@ supports need ID as filter argument. :layout: clean :style: green_border -.. note:: arguments and option filter can't be used at the same time. +.. note:: Arguments and the option filter can't be used at the same time. Options ------- @@ -68,7 +68,7 @@ style ~~~~~ ``:style:`` overwrites the need-specific style option and sets the same style for each need. -The original need provides the layout information , if not overwritten by :ref:`needextract_layout`. +The original need provides the layout information, if not overwritten by :ref:`needextract_layout`. See :ref:`styles` for a list of available styles. diff --git a/docs/directives/needflow.rst b/docs/directives/needflow.rst index 2b506153b..7437b7fc3 100644 --- a/docs/directives/needflow.rst +++ b/docs/directives/needflow.rst @@ -175,7 +175,7 @@ Adds information of used filters below generated flowchart. show_legend ~~~~~~~~~~~ -Adds a legend below generated flowchart. The legends contains all defined need-types and their configured color +Adds a legend below the generated flowchart. The legend contains all defined need-types and their configured color for flowcharts. .. need-example:: @@ -235,11 +235,11 @@ Must contain a comma separated list of link type names. By default, we show all link_types. An identical link can show up twice in the generated needflow, if the ``copy`` -option of a specific link type was set to ``True``. +option of a specific link type has been set to ``True``. In this case, the link_type **"link"** also contains the copies of the specified link_type and therefore there will be two identical connections in the needflow. -You can avoid this by not setting **"links**" in the ``link_type`` option. +You can avoid this by not setting **"links"** in the ``link_type`` option. You can set this option globally via the configuration option :ref:`needs_flow_link_types`. @@ -312,7 +312,7 @@ when using the ``graphviz`` engine. :show_link_names: :config: monochrome -You can apply multiple configurations together by separating them via ``,`` symbol. +You can apply multiple configurations together by separating them via the ``,`` symbol. .. need-example:: diff --git a/docs/directives/needgantt.rst b/docs/directives/needgantt.rst index 248e7ed9e..06ec23104 100644 --- a/docs/directives/needgantt.rst +++ b/docs/directives/needgantt.rst @@ -99,8 +99,8 @@ Options milestone_filter ~~~~~~~~~~~~~~~~ -We execute the ``milestone_filter`` on each need found by ``filter`` or any user related filter option. -If it is a match, we represent the need as a milestone instead of a task in gantt chart. +We execute the ``milestone_filter`` on each need found by ``filter`` or any user-related filter option. +If it matches, we represent the need as a milestone instead of a task in the gantt chart. ``milestone_filter`` must be a valid :ref:`filter_string`. @@ -222,7 +222,7 @@ Allowed values: ``daily``, ``weekly``, ``monthly``. Default: ``daily`` -Works only, if you set :ref:`needgantt_start_date` option. +Works only if you set the :ref:`needgantt_start_date` option. .. need-example:: @@ -237,8 +237,8 @@ Works only, if you set :ref:`needgantt_start_date` option. no_color ~~~~~~~~ -We derive the tasks and milestone color from the need-type configuration, -else we use the default PlantUML colors. +We derive the task and milestone colors from the need-type configuration, +otherwise we use the default PlantUML colors. .. needgantt:: Bug handling gantt :tags: gantt_example @@ -251,7 +251,7 @@ duration_option ~~~~~~~~~~~~~~~ Defines the option to use as the duration value. -We interpret the value in days, no matter what the name of the option is. +We interpret the value in days, regardless of the option name. You can set the duration option globally by using :ref:`needs_duration_option` in **conf.py**. @@ -287,7 +287,7 @@ completion_option ~~~~~~~~~~~~~~~~~ Defines the option to use as the completion value. -We interpret the value in percentage. +We interpret the value as a percentage. You can set the completion option globally by using :ref:`needs_completion_option` in **conf.py**. diff --git a/docs/directives/needimport.rst b/docs/directives/needimport.rst index afcfa6acb..c6141043c 100644 --- a/docs/directives/needimport.rst +++ b/docs/directives/needimport.rst @@ -97,22 +97,22 @@ This is useful if you want to import only a subset of the needs from the JSON fi filter ~~~~~~ -You can use the ``:filter:`` option to imports only the needs which pass the filter criteria. -This is a string that is evaluated as a Python expression, -it is less performant than the ``:ids:`` option, but more flexible. +You can use the ``:filter:`` option to import only the needs which pass the filter criteria. +This is a string that is evaluated as a Python expression. It is less performant than the ``:ids:`` option, +but more flexible. Please read :ref:`filter` for more information. hide ~~~~ -You can use the ``:hide:`` option to set the **hide** tag for all imported needs. -So they are not rendered on the page. +You can use the ``:hide:`` option to set the **hide** tag for all imported needs, +so they are not rendered on the page. collapse ~~~~~~~~ -The ``:collapse:`` will hide the meta-data information by default, if set to ``True``. +The ``:collapse:`` option will hide the metadata information by default, if set to ``True``. See also :ref:`need_collapse` description of :ref:`need`. .. warning:: @@ -124,8 +124,8 @@ See also :ref:`need_collapse` description of :ref:`need`. Customization ------------- -The following options can be set, which overwrite the related options in the imported need itself. -So you can decide what kind of layout or style to use during import. +The following options can be set, which overwrite the related options in the imported need itself, +allowing you to decide what kind of layout or style to use during import. * layout * style diff --git a/docs/directives/needpie.rst b/docs/directives/needpie.rst index daec17c7e..9f342933e 100644 --- a/docs/directives/needpie.rst +++ b/docs/directives/needpie.rst @@ -18,7 +18,7 @@ needpie If you provide an argument for the ``needpie``, we use it as the title. Each content line gets interpreted either as static float/int value or as a :ref:`filter_string`. -The amount of found needs by the filter string is then used as value. +The number of found needs by the filter string is then used as value. You can use :ref:`filter_func` with Python codes to define custom filters for ``needpie``. @@ -53,7 +53,7 @@ labels Use ``:labels:`` to set labels for each value. -``:labels:`` must get a comma separated string and the amount of labels must match the amount of +``:labels:`` must get a comma separated string and the number of labels must match the number of values/lines from content. .. need-example:: @@ -71,7 +71,7 @@ legend You can place a legend on the right side of the pie chart by setting the ``:legend:`` flag. -The ``:legend:`` flag does not support any values. +The ``:legend:`` flag does not support any additional values. .. need-example:: @@ -88,11 +88,11 @@ explode ~~~~~~~ ``:explode:`` takes a comma-separated list of floats and defines how much space a specific pie-part -moves of from center. +moves off from center. -The amount of values for ``:explode:`` must match the amount of values / content lines. +The number of values for ``:explode:`` must match the number of values / content lines. -Useful values for ``:explode:`` are between ``0`` and ``0.3`` +Useful values for ``:explode:`` are between ``0`` and ``0.3``. .. need-example:: @@ -187,7 +187,7 @@ In the past we had overlapping labels. See following diagram. .. image:: /_images/need_pie_overlapping_labels.png :alt: Example of a needpie with overlapping labels -Now overlapping labels are removed, and we automatically add a legend with removed information. +Now overlapping labels are removed, and a legend with the removed information is automatically added. .. need-example:: diff --git a/docs/directives/needreport.rst b/docs/directives/needreport.rst index 8cc7ec57b..f4053fda8 100644 --- a/docs/directives/needreport.rst +++ b/docs/directives/needreport.rst @@ -19,7 +19,7 @@ configuration variable, the plugin uses the default needs report template. The :ref:`needs_report_template` value is a path to the `jinja2 `_ template file. -You can use the template file to customise the content generated by ``needreport``. +You can use the template file to customise the content generated by ``needreport``. .. note:: diff --git a/docs/directives/needsequence.rst b/docs/directives/needsequence.rst index 27c4ed231..7b496813c 100644 --- a/docs/directives/needsequence.rst +++ b/docs/directives/needsequence.rst @@ -65,17 +65,17 @@ needsequence :triggers: USER_D :style: yellow_border -Sequence diagrams supports special needs-combinations, in which one type represents some kind of a ``participant`` +Sequence diagrams support special needs-combinations, in which one type represents some kind of a ``participant`` and another, linked need is representing the ``message``. |br| -Examples for this relationship are: Sender-Receiver communication , Role-Activity processes or Tool-Artifact relations. +Examples for this relationship are: Sender-Receiver communication, Role-Activity processes or Tool-Artifact relations. ``needsequence`` needs at least one start-need, defined by its ``id`` in the ``:start:`` option. The first need represents the ``participant``. The next, linked need(s) is representing the ``message``. Needs linked from a ``message`` are interpreted as ``participant`` again and so on. |br| -So the linking must be really clean to get nice, meaningful sequence diagrams out of it. +So the linking must be very clean to get nice, meaningful sequence diagrams. -The used need-type is unimportant. +The need type used is unimportant. .. uml:: :caption: Participant-Message flow @@ -141,12 +141,12 @@ filter ~~~~~~ You can use the ``:filter:`` option to filter participants. -We ignore all participants that does not fulfill the filter_string. +We ignore all participants that do not fulfill the filter_string. See :ref:`filter_string` for more information. Default: None (no active filtering) -You can use this function to filter out a specific participant. +You can use this option to filter out a specific participant. As an example, we use the same ``needsequence`` from the beginning, but without ``USER_C / Expert``: .. need-example:: diff --git a/docs/directives/needservice.rst b/docs/directives/needservice.rst index c5bb34679..8daae7c88 100644 --- a/docs/directives/needservice.rst +++ b/docs/directives/needservice.rst @@ -17,7 +17,7 @@ needservice 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. +found data element in the returned data. These need objects can then be used and referenced as all other need objects, e.g. by filtering them via :ref:`needtable`. @@ -45,7 +45,7 @@ debug ~~~~~ Set ``debug`` to get debug-output of the ``needservice`` only. No needs will be created. -Useful to understand the return values of services or to figure out, why a connection can not be established, for example: +Useful to understand the return values of services or to figure out why a connection cannot be established, for example: .. code-block:: rst @@ -58,7 +58,7 @@ 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. -For example, by awaiting a json-string with a more complex configuration or by just ignoring the content. +For example, by expecting a JSON string with a more complex configuration or by just ignoring the content. Please take a look into the related service documentation for more information. @@ -70,7 +70,7 @@ For details, please take a look into its specific documentation under :ref:`gith The service queries ``GitHub`` for issues in the **Sphinx-Needs** repository that have *node* and *latexpdf* in their content. -.. tip:: Click the small arrow under the need id to see all meta data. +.. tip:: Click the small arrow under the need id to see all metadata. .. need-example:: diff --git a/docs/directives/needtable.rst b/docs/directives/needtable.rst index 8eed70d11..eff2ada85 100644 --- a/docs/directives/needtable.rst +++ b/docs/directives/needtable.rst @@ -188,9 +188,9 @@ style_row .. versionadded:: 0.4.1 -You can use the ``style_row`` option to set a specific class-attribute for the table-row representation and use **CSS** to select the class-attribute +You can use the ``style_row`` option to set a specific class-attribute for the table-row representation and use **CSS** to select the class-attribute. -Also, you can set specific layout for the row. +Also, you can set a specific layout for the row. .. need-example:: @@ -295,7 +295,7 @@ By default, we use ``id_complete`` if we don't set a sort option. :tags: ex_row_color :style: table -In this case, we set the sort option to ``status``. So *EX_ROW_3* is above of *EX_ROW_2*. +In this case, we set the sort option to ``status``. So *EX_ROW_3* is above *EX_ROW_2*. .. need-example:: @@ -320,7 +320,7 @@ In this case, we set the sort option to ``status``. So *EX_ROW_3* is above of *E .. note:: 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. + By default, tables generated with DataTables use Javascript to sort results. .. _needtable_class: diff --git a/docs/directives/needuml.rst b/docs/directives/needuml.rst index 3029ad853..c09a3d1e5 100644 --- a/docs/directives/needuml.rst +++ b/docs/directives/needuml.rst @@ -184,14 +184,14 @@ flow(id) Loads a Sphinx-Need object as PlantUML object. We use the same layout used for :ref:`needflow`. -This functions represents each Need the same way. +This function represents each need the same way. .. versionchanged:: 1.0.3 - In the past the returned plantuml representation string ends with a + In the past, the returned PlantUML representation string ended with a newline. Now it is up to the author of the Jinja template to write - 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()`. + the newline, which is normally the case anyway. E.g. see the following + example, where the two `flow()` are separated by a newline. With this + approach, it is possible to write PlantUML code following `flow()`. E.g. see even the following example, with text following `{{flow("COMP_001")}}`. diff --git a/docs/docker.rst b/docs/docker.rst index 066eec40a..9a13cb6d2 100644 --- a/docs/docker.rst +++ b/docs/docker.rst @@ -30,7 +30,7 @@ use case. ~~~~~~~~~~~~~~~~~~~~~ .. _latest_version: -This is the defacto docker image (size ~ 350MB). If you are not sure about what +This is the de facto docker image (size ~ 350MB). If you are not sure about what your requirements are, you probably want to use this one. 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. @@ -140,7 +140,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 script allows you to choose between the html and pdf variant and the Sphinx-Needs version to be installed. Usage diff --git a/docs/dynamic_functions.rst b/docs/dynamic_functions.rst index 0ae9badb4..798ad8484 100644 --- a/docs/dynamic_functions.rst +++ b/docs/dynamic_functions.rst @@ -8,7 +8,7 @@ Dynamic functions provide a mechanism to specify need fields or content that are We do this by giving an author the possibility to set a function call to a predefined function, which calculates the final value **after all needs have been collected**. For instance, you can use the feature if the status of a requirement depends on linked test cases and their status. -Or if you will request specific data from an external server like JIRA. +Or if you want to request specific data from an external server like JIRA. To refer to a dynamic function, you can use the following syntax: @@ -104,7 +104,7 @@ inside your **conf.py** file, to add a :py:class:`.DynamicFunction`: .. warning:: - Assigning a function to a Sphinx option will deactivate the incremental build feature of Sphinx. + Assigning a function to a Sphinx option deactivates the incremental build feature of Sphinx. Please use the :ref:`Sphinx-Needs API ` and read :ref:`inc_build` for details. **Recommended:** You can use the following approach we used in our **conf.py** file to register dynamic functions: @@ -125,8 +125,8 @@ Restrictions incoming_links ++++++++++++++ -Incoming links are not available when dynamic functions gets calculated. +Incoming links are not available when dynamic functions are 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. +be recalculated. This is done automatically, but not until all dynamic functions are resolved. diff --git a/docs/filter.rst b/docs/filter.rst index ba673b6bd..a431c33ca 100644 --- a/docs/filter.rst +++ b/docs/filter.rst @@ -25,7 +25,7 @@ filters for status, tags, types and filter. For **:status:**, **:tags:** and **:types:** values are separated by "**;**". **:filter:** gets evaluated. -The logic, if a need belongs to the final result list, is as followed:: +The logic for determining if a need belongs to the final result list is as follows:: status = (open OR in_progress) AND tags = (user OR login) AND types = (req OR spec) AND eval(filter) is True @@ -218,7 +218,7 @@ The second parameter should be one of the above variables(status, id, content, . .. dropdown:: Show example - This example uses a regular expressions to find all needs with an e-mail address in title. + This example uses a regular expression to find all needs with an e-mail address in title. .. need-example:: @@ -235,7 +235,7 @@ Filter string performance .. versionadded:: 4.0.0 The filter string is evaluated by default for each need and need part -and, therefore, can be become a performance bottleneck for projects with large numbers of needs. +and, therefore, can become a performance bottleneck for projects with large numbers of needs. To improve performance, certain common patterns are identified and optimized by the filter engine, and so using such patterns is recommended: @@ -303,7 +303,7 @@ If ``filter code`` is used, all other filter related options (like ``status`` or .. warning:: This feature executes every given Python code. - So be sure to trust the input/writers. + So be sure to trust the input and writers. .. _filter_func: @@ -345,12 +345,12 @@ Arguments ~~~~~~~~~ .. versionadded:: 0.7.6 -Filter function are supporting arguments: ``filter_file.own_filter_code(value_1,value_2)``. +Filter functions support arguments: ``filter_file.own_filter_code(value_1,value_2)``. Please note, that the part between ``(...)`` is just a comma separated list and each element will be given as string to the function. -The functions get the values as part of ``**kwargs`` with the name is ``arg``, starting from ``1``. +The functions get the values as part of ``**kwargs`` with the name ``arg``, starting from ``1``. Example: @@ -367,7 +367,7 @@ Example: if int(need["price"]) > int(kwargs["arg1"]) or need["status"] == kwargs["arg3"]: results.append(need) -The function developer is responsible to perform any needed typecast. +The function developer is responsible for performing any needed typecasts. Needpie ~~~~~~~ @@ -400,7 +400,7 @@ Example: Filter matches nothing ---------------------- -Depending on the directive used a filter that matches no needs may add text to inform that no needs are found. +Depending on the directive used, a filter that matches no needs may add text to inform you that no needs are found. The default text "No needs passed the filter". @@ -413,7 +413,7 @@ filter_warning Add specific text with this option or add no text to display nothing. The default text will not be shown. -The specified output could be styled with the css class ``needs_filter_warning`` +The specified output can be styled with the CSS class ``needs_filter_warning`` More Examples ------------- diff --git a/docs/index.rst b/docs/index.rst index 092aa31ba..754d31718 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -64,23 +64,23 @@ Introduction .. 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, + enabling you to define, link, and analyze 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 - Allows you to define the exact way of using and configuring need objects, + Allows you to define exactly how to use and configure 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 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. + and the :ref:`built-in API ` enables 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 - Import and export mechanisms facilitate external synchronization with other tools, + Import and export mechanisms enable external synchronization with other tools, such as `JIRA `__, :ref:`GitHub `, or spreadsheets, allowing for embedding tickets, requirements and other information into your documentation. @@ -91,8 +91,8 @@ Introduction .. 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 `__. + Allows you to create specific objects for architecture elements, which can be reused and recombined + in different flow diagrams and higher-level architecture elements, using `PlantUML `__. ---------------- @@ -147,7 +147,7 @@ See more from `useblocks `__ to enhance your sphinx-needs 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 such as Git repositories, Jinja-based files, or symlinks. +++ .. button-link:: https://sphinx-collections.readthedocs.io/en/latest/ diff --git a/docs/installation.rst b/docs/installation.rst index c8d81feda..b4f08a682 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -135,7 +135,7 @@ Install PlantUML 1. Download the latest version of the plantuml.jar file: http://sourceforge.net/projects/plantuml/files/plantuml.jar/download -2. Make a new folder called ``utils`` inside your docs folder. Copy the ``plantuml.jar`` file into the ``utils`` folder. +2. Create a new folder called ``utils`` inside your docs folder. Copy the ``plantuml.jar`` file into the ``utils`` folder. 3. Install the plantuml sphinx extension: ``pip install sphinxcontrib-plantuml``. 4. Add ``sphinxcontrib.plantuml`` to the sphinx extension list in ``conf.py`` @@ -157,10 +157,10 @@ Install PlantUML plantuml_output_format = 'png' -The final configuration contains already a setup for building and deploying the documentation on +The final configuration already contains a setup for building and deploying the documentation on `ReadTheDocs `_. -ReadTheDocs provides ``plantuml.jar`` already on their system, so do not store it inside your source version control system. +ReadTheDocs already provides ``plantuml.jar`` on their system, so do not store it inside your source version control system. Using Docker @@ -168,7 +168,7 @@ Using Docker Sphinx-Needs is also available as a Docker Image. -See :ref:`docker` for the documentation and hints how to use it. +See :ref:`docker` for documentation and hints on how to use it. .. _ide: .. _ide_vscode: @@ -178,4 +178,4 @@ VS Code Extension The VS Code extension `ubCode `_ provides support for Sphinx-Needs. -See more details in the `Documentation `_. +See more details in the `documentation `_. diff --git a/docs/layout_styles.rst b/docs/layout_styles.rst index d4d3d9bce..fd464c626 100644 --- a/docs/layout_styles.rst +++ b/docs/layout_styles.rst @@ -8,7 +8,7 @@ Layouts & Styles Layouts are defined by a preconfigured table grid and the data, which shall be shown inside specific grid cells. Styles define mostly the color of a need. -Both features can be set directly during need-configuration or inside the sphinx **conf.py** file. +Both features can be set directly during need-configuration or inside the Sphinx **conf.py** file. **Sphinx-Needs** provides some preconfigured, ready-to-use standard layouts: @@ -20,13 +20,13 @@ 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. +Layouts use 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. +There can be multiple layouts using the same :ref:`grid system `, but showing different data. E.g. a layout for bugs and one for specifications. **Sphinx-Needs** comes with some predefined layouts. -But the user is free to create own layouts and use only them. +But the user is free to create their own layouts and use only them. Most useful layouts are: @@ -43,10 +43,10 @@ Most useful layouts are: * The standard **Sphinx-Needs** layout - * complete * :ref:`grid_complex` - * Divided head, meta, footer rows. Showing really all user-added data. + * Divided head, meta, footer rows. Shows all user-added data. - * focus * :ref:`grid_content` - * Content focused layout. Showing content only. Nothing more. + * Content-focused layout. Shows content only. Nothing more. **Examples** @@ -111,8 +111,8 @@ There are also some *extensions* for the layouts above available: * :ref:`grid_content_side_right` * Adds a small footer to the right side of content, showing the need id. -The layouts ``clean_l``, ``clean_r``, ``clean_lp`` and ``clean_rp`` are using the value from the field ``image`` as -source for the image in the side element. This field must made available via :ref:`needs_extra_options`. +The layouts ``clean_l``, ``clean_r``, ``clean_lp`` and ``clean_rp`` use the value from the field ``image`` as +source for the image in the side element. This field must be made available via :ref:`needs_extra_options`. If you need another field as source, you must create your own layout. **Examples** @@ -190,8 +190,8 @@ Special layouts: * Comment - * debug * :ref:`grid_content_footer` - * Shows **all** meta data (also internal ones). - Useful do see what data is available for a need and which can be used in :ref:`filter_string`. + * Shows **all** meta data (including internal ones). + Useful to see what data is available for a need and which can be used in :ref:`filter_string`. **Examples** @@ -222,7 +222,7 @@ Or set it locally for each need by using :ref:`need_layout` option:: Defining own layouts ~~~~~~~~~~~~~~~~~~~~ -Own layouts can be defined by using the the config parameter :ref:`needs_layouts` in your **conf.py** file. +Own layouts can be defined by using 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:: @@ -245,7 +245,7 @@ E.g. grid ``simple`` is not supporting ``footer`` area. The values of a specific layout-structure area definition must be a list, where each entry must be a string and represents a single line in the later need representation. -This line can contain :ref:`layout_functions`, which care about getting need-data or adding links. +This line can contain :ref:`layout_functions`, which handle getting need-data or adding links. .. note:: @@ -254,7 +254,7 @@ This line can contain :ref:`layout_functions`, which care about getting need-dat .. note:: - The ``content`` area of a grid can not be overwritten. It is always there and can't be changed or replaced. + The ``content`` area of a grid cannot be overwritten. It is always there and can't be changed or replaced. .. _layout_line: @@ -267,7 +267,7 @@ A layout line may look like this:: This line contains: - * a rst text, which supports common inline roles (bold, italic): + * rst text, which supports common inline roles (bold, italic): ``**style**: _my_`` * a layout function, which gets executed and returns a string: ``<>`` @@ -286,7 +286,7 @@ 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. -Sometimes an argument for a layout function shall be based on a given need option. In this cases the option name +Sometimes an argument for a layout function shall be based on a given need option. In these cases the option name can be surrounded by ``{{ .. }}``. As example, there may be an ``author`` option in a bug-need and you want to show a picture of the author in the grid ``simple_side_right_partial``. @@ -347,7 +347,7 @@ Here is the complete used code Layout functions ++++++++++++++++ -To get custom data into your layout the usage of layout function is needed. +To get custom data into your layout, the usage of layout functions is needed. A layout function may look like ``<>`` Available layout functions are: @@ -384,9 +384,9 @@ 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. +Styles handle mostly colors for background, border and so on for a need. +Their definition is done in css files, so **Sphinx-Needs** only cares about setting the correct class in HTML +output. This also means that styles do not have any impact on the need design in PDFs and other output formats. Default styles are: @@ -401,7 +401,7 @@ Default styles are: - * **blue** * Blue background - * **discreet** - * Background color is only a little bit lighter/darker as the page background + * Background color is only a little bit lighter/darker than the page background - * **green_border** * Green border, but normal background - * **red_border** @@ -421,7 +421,7 @@ Default styles are: - * **blue_bar** * 10 % of width blue on right side, rest with normal background - * **discreet_border** - * Border color is only a little bit lighter/darker as the page background + * Border color is only a little bit lighter/darker than the page background - * **clean** * Removes all style information. Looks like normal text. Mostly used with layout **focus**. @@ -541,7 +541,7 @@ 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 +* Set your own css on Sphinx level .. _styles_css: @@ -571,7 +571,7 @@ 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:: +can provide your own CSS file by registering it inside your conf.py:: html_css_files = ['css/my_custom.css'] @@ -599,7 +599,7 @@ The above line contains the following css classes: Please note, that the classes added by **Sphinx-Needs** always contain a prefix: ``needs_grid_``, ``needs_layout_``, ``needs_style_``. -So if a user defined layout has the name ``specification_layout``, the related css class is +So if a user-defined layout has the name ``specification_layout``, the related css class is ``needs_layout_specification_layout`` .. _grids: diff --git a/docs/performance/debug.rst b/docs/performance/debug.rst index 81cbed01b..003723478 100644 --- a/docs/performance/debug.rst +++ b/docs/performance/debug.rst @@ -6,7 +6,7 @@ Runtime debugging .. versionadded:: 1.3.0 The build time of Sphinx is based on a lot of indicators, especially when Sphinx-Needs is used and self-written -filters and warning functions got registered. Then it might happen that a build gets quite slow and it is hard to figure +filters and warning functions are registered. Then it might happen that a build gets quite slow and it is hard to figure out why this is the case. To get an overview about what takes how long, an integrated time measurement is available, which @@ -16,7 +16,7 @@ To activate it, simply add the following to the project ``conf.py`` file:: needs_debug_measurement = True -This will perform measurements and gives some output in three formats: +This will perform measurements and provides output in three formats: * Some basic stats on the command line after the build * A JSON file ``debug_measurement.json`` in the current build folder, which contains **all** captured data @@ -33,11 +33,11 @@ This will perform measurements and gives some output in three formats: .. warning:: Do not use this function in Sphinx parallel mode, as this will result in incorrect data. - Mainly because the used result variables get not synced between the different worker processes. + Mainly because the used result variables are not synced between the different worker processes. Technical details ----------------- -If you need to activate the measurement for additional Sphinx-Needs functions, use the ``measure_time()`` decorator. +To activate measurement for additional Sphinx-Needs functions, use the ``measure_time()`` decorator. .. autofunction:: sphinx_needs.debug.measure_time \ No newline at end of file diff --git a/docs/performance/script.rst b/docs/performance/script.rst index e2587aaca..b53a32cfe 100644 --- a/docs/performance/script.rst +++ b/docs/performance/script.rst @@ -8,7 +8,7 @@ Performance & Profiling script The performance script got its own Sphinx extension: `Sphinx-Performance `_. - This extension is based on the described script, but is more powerfull and better maintained. + This extension is based on the described script, but is more powerful and better maintained. It can also be used for general performance analysis of Sphinx and its extensions. The performance of **Sphinx-Needs** can be tested by a script called ``performance_test.py`` inside @@ -66,7 +66,7 @@ are used. 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. +The parallel execution can be used by any documentation build; just use the `-j` option. Example, which uses 4 processes in parallel: ``sphinx-build -j 4 -b html . _build/html`` @@ -100,14 +100,14 @@ If this option is used, a ``profile`` folder gets created in the current working ``--profile`` can be used several times. -These profile can be also created outside the performance test with each documentation project. -Simply set a environment variable called ``NEEDS_PROFILING`` and set the value to the needed profiles. +These profiles can also be created outside the performance test with any documentation project. +Simply set an environment variable called ``NEEDS_PROFILING`` and set the value to the needed profiles. Example for Linux: ``export NEEDS_PROFILING=NEEDTABLE,NEED_PRINT``. -Analysing profile +Analyzing profile ~~~~~~~~~~~~~~~~~ Use ``snakeviz`` together with ``--profile `` to open automatically a graphical analysis of the generated profile file. diff --git a/docs/roles.rst b/docs/roles.rst index fc2edf85f..c2e9e9e90 100644 --- a/docs/roles.rst +++ b/docs/roles.rst @@ -83,7 +83,7 @@ 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. -This sub-ids can be linked and referenced in other need functions like links and co. +These sub-ids can be linked and referenced in other need functions like links and other functions. The used need_part id can be freely chosen, but should not contain any whitespaces or dots. @@ -94,7 +94,7 @@ The used need_part id can be freely chosen, but should not contain any whitespac :tags: car :status: open - My new car must be the fastest on the world. Therefor it shall have: + My new car must be the fastest in the world. Therefore it shall have: * :need_part:`(1)A top speed of 300 km/h` * :np:`(2) An acceleration of 200 m/s² or much much more` @@ -109,7 +109,7 @@ The used need_part id can be freely chosen, but should not contain any whitespac Requirements :need:`my_car_1.1` and :need:`my_car_1.2` are no problem and can be realised by doing rocket science. - But no way to get :need:`my_car_1.awesome_3` realised. + But no way to get :need:`my_car_1.awesome_3` realized. Reference to a part of a need from outside need scope: :need:`my_car_1.2`. @@ -160,7 +160,7 @@ See :ref:`filter_string` for more information. .. note:: If backslashes ``\`` are used inside the regex function ``search``, please make sure to double them as in python - one ``\`` needs to be represented by ``\\``. + one ``\`` must be represented by ``\\``. .. note:: diff --git a/docs/schema/index.rst b/docs/schema/index.rst index e5cd48faa..a65a37663 100644 --- a/docs/schema/index.rst +++ b/docs/schema/index.rst @@ -27,7 +27,7 @@ Imagine the following modeling of need items: There are a few things to note about this setup: -- the extra options ``efforts``, ``approval`` and +- the extra options ``efforts``, ``approved`` and ``asil`` (for **A**\ utomotive **S**\ ecurity **I**\ ntegrity **L**\ evel) are typed - the assigned extra options differ between need types - the fields may be optional for a need type, required or even not allowed @@ -149,7 +149,7 @@ Local validation checks individual need properties without requiring information - has a minimum value of 0 - has a maximum value of 20 -- the ``approval`` field +- the ``approved`` field - is of type boolean - is optional for ``spec`` and ``feat`` and disallowed for ``impl`` @@ -463,8 +463,8 @@ Network validation can be nested to validate multi-hop link chains: This validates that: 1. A safe implementation links to safe specifications -#. Those specifications in turn link to safe features -#. Both link levels have minimum/maximum count requirements +2. Those specifications in turn link to safe features +3. Both link levels have minimum/maximum count requirements Schema Components ----------------- diff --git a/docs/services/github.rst b/docs/services/github.rst index e72605722..0a3a78ec4 100644 --- a/docs/services/github.rst +++ b/docs/services/github.rst @@ -14,7 +14,7 @@ for each information type: 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. -Each services creates normally multiple need objects for each element found by querying the GitHub API. +Each service normally creates multiple need objects for each element found by querying the GitHub API. **Example of an imported github issue**: @@ -30,7 +30,7 @@ Each services creates normally multiple need objects for each element found by q Example of a github Issue collected with Sphinx-Needs. -Directive options, which can also used for normal needs, can also be set for ``needservice`` directive. +Directive options, which can also be used for normal needs, can also be set for ``needservice`` directive. Also the content part of ``needservice`` is added as extra data to the end of the finally created needs. **Example**: @@ -69,7 +69,7 @@ Setting ``query`` or ``specific`` option is mandatory for services ``github-issu GitHub counts the performed API requests and may reject new requests, if the rate limit is exceeded. This seems to be **10 requests per minute for search-API** for unauthenticated users. - You can higher this limit to **30 requests**, if you provide a username and token in the service config. + You can increase this limit to **30 requests**, if you provide a username and token in the service config. **Sphinx-Needs** will support you with the current rate limit status, if a request got rejected. @@ -202,7 +202,7 @@ GitHub by default. If a company internal ``GitHub Enterprise`` instance shall be addressed, you should configure an additional service to deal with both (cloud and company instance) and being able to set company specific configuration options. -Please see the this example for a ``Github Enterprise`` configuration in your **conf.py** file: +Please see this example for a ``Github Enterprise`` configuration in your **conf.py** file: .. code-block:: python @@ -231,7 +231,7 @@ Please see the this example for a ``Github Enterprise`` configuration in your ** } ``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 +initialization options. In this case you must tell the generic ``GitHubService`` class which kind of information 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 diff --git a/docs/services/index.rst b/docs/services/index.rst index 3214734e1..2fc6a3ec9 100644 --- a/docs/services/index.rst +++ b/docs/services/index.rst @@ -100,7 +100,7 @@ All you need to do is to set the Python service class, which must be mentioned u 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`. +For a complex example please see the GitHub service please take a look into its chapter :ref:`service_github_custom`. Own services @@ -150,7 +150,7 @@ Example of a basic service: 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 needs to be serializable via json.dump(). debug_data = {'custom_debug': 'data'} return debug_data diff --git a/docs/services/open_needs.rst b/docs/services/open_needs.rst index f79a0e3cf..ca6ef3709 100644 --- a/docs/services/open_needs.rst +++ b/docs/services/open_needs.rst @@ -10,7 +10,7 @@ The `Open-Needs `__ service retrieves Need objects from creates Sphinx-Needs objects during build time. The service creates need objects for each element found by querying the Open-Needs REST-API based server. -The service name for Open-Needs service must be ``open-needs``. +The service name for the Open-Needs service must be ``open-needs``. Example of an imported open-needs: @@ -60,7 +60,7 @@ The final address of the endpoint. E.g.: ``/api/needs/`` max_content_lines ################# -Maximum amount of lines from open-needs objects description/content to be used in need content. +Maximum number of lines from the open-needs object's description/content to be used in the need content. Config ------ @@ -88,7 +88,7 @@ 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. +The field names of a service object often do not 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}}`` @@ -133,7 +133,7 @@ Goal: The need option ``author`` shall be set to the last and first names. The last and first names information are stored in the retrieved :ref:`Open-Needs ` data under ``lastname`` and ``firstname``. -The **mapping** entry for ``author`` would like this: +The **mapping** entry for ``author`` would look like this: .. code-block:: python @@ -167,7 +167,7 @@ Jinja support is also available, so that service data is available and can be ac mappings_replaces ################# -There are use cases, where a value inside service data is not valid for a Sphinx-Needs options. +There are use cases where a value inside the service data is not valid for a Sphinx-Needs option. 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. **mappings_replaces** can replace strings defined by a regular expression with a new value. This replacement is performed for all mappings. @@ -177,7 +177,7 @@ 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. -This can be done by using ``extra_data``, which adds this kind of information to the end of the content of a need object. +This can be done by using ``extra_data``, which adds this kind of information to the end of a need object's content. The logic and syntax is the same as used by `mapping <#mapping>`_. @@ -218,7 +218,7 @@ Examples .. hint:: - The below examples are just images, as no Open-Needs Server instance was available during documentation build. + The examples below 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..8207f3f47 100644 --- a/docs/support.rst +++ b/docs/support.rst @@ -6,23 +6,23 @@ Support If you find any bugs or have an idea for an improvement, feel free to open an entry on our issue-tracker at github: https://github.com/useblocks/sphinx-needs -We are happy for each new entry and support wherever we can. +We appreciate every entry and will 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 +We are a bunch of passionate developers, who normally work on process-, tool-, or embedded-related projects for automotive companies around the world. -Fastest way of reaching us is via e-mail: mail@useblocks.com. +The fastest way of reaching us is via e-mail: mail@useblocks.com. .. image:: /_images/logos/useblocks_logo.png :align: center :width: 100px :target: http://useblocks.com -Convince your team +Convince Your Team ------------------ Need some material to convince team members and managers to use Sphinx together with Sphinx-Needs for your project? diff --git a/docs/tutorial.rst b/docs/tutorial.rst index 862983fdc..8fc06955a 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -45,7 +45,7 @@ Each item must have at least: - a title, and - a description. -A need item is a generic object which can become anything you you require for your project: a requirement, a test case, a user story, a bug, an employee, a product... +A need item is a generic object which can become anything you require for your project: a requirement, a test case, a user story, a bug, an employee, a product... sphinx-needs comes with some default types: ``req``, ``spec``, ``impl``, and ``test``, which can be used as directives: @@ -173,7 +173,7 @@ Lets also add some more need items to our plan: 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. + and 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 @@ -235,7 +235,7 @@ Here we filter by the tag we set on the imported items above: .. 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. + but if you look at the items, they will now have the additional link and status fields. .. seealso:: @@ -301,7 +301,7 @@ Finally, we can display a :ref:`flow diagram ` of the need items, to a [status == 'in progress']:0000FF, [status == 'closed']:00FF00 -.. dropdown:: Aternative use of Graphviz engine +.. dropdown:: Alternative use of Graphviz engine You can also use the Graphviz engine to render the flow diagram, by setting the ``engine`` option to ``graphviz``: