📚 Improve on docs grammar

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:
 

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
 +++++

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.

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 <https://docs.cypress.io/guides/getting-started/installing-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 <https://docs.cypress.io/guides/guides/command-line>`_.
-* 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 <https://docs.cypress.io/guides/getting-started/installing-cypress>`_.
+* Verify if Cypress is installed correctly and is executable by running: ``npx cypress verify``. See this page for more information about `Cypress commandline <https://docs.cypress.io/guides/guides/command-line>`_.
+* 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 <https://docs.cypress.io/>`_. 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 <https://docs.cypress.io/>`_. 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,36 +189,35 @@ 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.
 
 .. 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
 ----------
 
 **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

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: