Sphinx-Needs

https://sphinx-needs.readthedocs.io/en/stable
Admin
Sphinx-Needs is a Sphinx extension for defining, linking, and analyzing engineering objects like...
Tokens:108,671
Snippets:1,276
Trust Score:9.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install Sphinx-Needs from Source

Source: https://sphinx-needs.readthedocs.io/en/stable/installation.html

Clone the repository and install Sphinx-Needs using pip from the local source code.

```bash
git clone https://github.com/useblocks/sphinx-needs
cd sphinx-needs
pip install .

```

--------------------------------

### Install Documentation Requirements

Source: https://sphinx-needs.readthedocs.io/en/stable/contributing.html

Install the Python dependencies required for building the official documentation.

```bash
pip install -r docs/requirements.txt
```

--------------------------------

### Run Sphinx Build Example

Source: https://sphinx-needs.readthedocs.io/en/stable/schema/index.html

Command to execute the Sphinx build for the schema example documentation. Ensure you are in the correct directory.

```bash
tests/doc_test/doc_schema_example $ uv run sphinx-build -b html . _build
```

--------------------------------

### Custom Layout Configuration and Usage

Source: https://sphinx-needs.readthedocs.io/en/stable/layout_styles.html

Complete example demonstrating the configuration of a custom layout named 'example' in `conf.py` and its application to a specific need in reStructuredText.

```python
# conf.py
# ------- 

# Make the author option valid
needs_fields = {"author": {}}

# Define own layout
needs_layouts = {
    'example': {
        'grid': 'simple_side_right_partial',
        'layout': {
            'head': ['**<<meta("title")>>** for *<<meta("author")>>*'],
            'meta': ['**status**: <<meta("status")>>',
                     '**author**: <<meta("author")>>'],
            'side': ['<<image("_images/{{author}}.png", align="center")>>']
        }
    }
}

```

```rst
.. spec:: My test spec
   :author: daniel
   :status: open
   :layout: example
   :tags: example
   :style: yellow, blue_border


```

--------------------------------

### Install Development Dependencies

Source: https://sphinx-needs.readthedocs.io/en/stable/contributing.html

Install Sphinx-Needs with development extras for testing, benchmarking, and documentation.

```bash
pip install sphinx-needs[test,benchmark,docs]
```

--------------------------------

### needgantt with Start Date

Source: https://sphinx-needs.readthedocs.io/en/stable/directives/needgantt.html

Example of using the `start_date` option to set a specific starting point for the gantt chart. All task and milestone dates will be calculated relative to this date.

```directives
.. needgantt:: Bug handling gantt
   :tags: gantt_example
   :milestone_filter: type == 'milestone'
   :start_date: 2020-03-25

```

--------------------------------

### Example: Sphinx-Needs String Link Configuration

Source: https://sphinx-needs.readthedocs.io/en/stable/configuration.html

This example demonstrates configuring `needs_string_links` to create links to the Sphinx-Needs documentation and GitHub issues based on option values.

```python
needs_string_links = {
    # Adds link to the Sphinx-Needs configuration page
    'config_link': {
        'regex': r'^(?P<value>\w+)$',
        'link_url': 'https://sphinx-needs.readthedocs.io/en/latest/configuration.html#{{value | replace("_", "-")}}',
        'link_name': 'Sphinx-Needs docs for {{value | replace("_", "-") }}',
        'options': ['config']
    },
    # Links to the related github issue
    'github_link': {
        'regex': r'^(?P<value>\w+)$',
        'link_url': 'https://github.com/useblocks/sphinx-needs/issues/{{value}}',
        'link_name': 'GitHub #{{value}}',
        'options': ['github']
    }
}
```

--------------------------------

### Install Sphinx-Needs with pip

Source: https://sphinx-needs.readthedocs.io/en/stable/installation.html

Use this command to install the latest stable version of Sphinx-Needs.

```bash
pip install sphinx-needs

```

--------------------------------

### Install and Run Pre-commit Hooks

Source: https://sphinx-needs.readthedocs.io/en/stable/contributing.html

Install pre-commit to automatically run formatting and linting checks on every commit, or run them manually on all files.

```bash
pre-commit install
pre-commit run --all-files
```

--------------------------------

### Profiling Command Example

Source: https://sphinx-needs.readthedocs.io/en/stable/performance/script.html

Example command to run performance tests with specific profiling options enabled (NEEDTABLE, NEED_PROCESS) and visualize results with snakeviz.

```bash
python performance_test.py series --needs 10 --pages 10 --profile NEEDTABLE --profile NEED_PROCESS --snakeviz

```

--------------------------------

### Defining Multiple Needs with Tags and Links

Source: https://sphinx-needs.readthedocs.io/en/stable/filter.html

Example demonstrating the definition of various Sphinx-Needs directives (req, spec, impl, test) with their respective options like status, tags, and links. This serves as a setup for filtering examples.

```rst
.. req:: My first requirement
   :status: open
   :tags: requirement; test; awesome

   This is my **first** requirement!!

   .. note:: You can use any rst code inside it :)

.. spec:: Specification of a requirement
   :id: OWN_ID_123
   :links: R_F4722

   Outgoing links of this spec: :need_outgoing:`OWN_ID_123`.

.. impl:: Implementation for specification
   :id: IMPL_01
   :links: OWN_ID_123

   Incoming links of this spec: :need_incoming:`IMPL_01`.

.. test:: Test for XY
   :status: implemented
   :tags: test; user_interface; python27
   :links: OWN_ID_123; IMPL_01

   This test checks :need:`IMPL_01` for :need:`OWN_ID_123` inside a
   Python 2.7 environment.

```

--------------------------------

### New needs.links Configuration

Source: https://sphinx-needs.readthedocs.io/en/stable/changelog.html

Example of the new configuration for defining links.

```toml
[needs.links.blocks]
incoming = "is blocked by"

```

--------------------------------

### Example TOML Configuration for Needs

Source: https://sphinx-needs.readthedocs.io/en/stable/configuration.html

Example of how to configure Sphinx-Needs options within a TOML file under the `[needs]` section.

```toml
[needs]
id_required = true
id_length = 3
types = [
   {directive="req", title="Requirement", prefix="R_", color="#BFD8D2", style="node"},
   {directive="spec", title="Specification", prefix="S_", color="#FEDCD2", style="node"},
]
```

--------------------------------

### Sphinx Configuration (conf.py)

Source: https://sphinx-needs.readthedocs.io/en/stable/schema/index.html

Basic Sphinx configuration file for the example, enabling the 'sphinx_needs' extension and setting up project details.

```python
project = "Docs modeling example"

extensions = ["sphinx_needs"]

templates_path = ["_templates"]
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]

needs_from_toml = "ubproject.toml"

html_theme = "alabaster"


```

--------------------------------

### Open Needs Service Directive and Table Example

Source: https://sphinx-needs.readthedocs.io/en/stable/services/open_needs.html

Example of using the needservice directive with a prefix and parameters, followed by a needtable filtered by the imported needs.

```rst
.. needservice:: open-needs
   :prefix: ONS_
   :params: skip=0;limit=10

.. needtable::
   :filter: "ONS" in id


```

--------------------------------

### Synchronize Dependencies with uv

Source: https://sphinx-needs.readthedocs.io/en/stable/contributing.html

Use uv to install dependencies into an isolated environment.

```bash
uv sync
```

--------------------------------

### New needs.fields Configuration

Source: https://sphinx-needs.readthedocs.io/en/stable/changelog.html

Example of the new configuration for defining fields with schema constraints.

```toml
[needs.fields.priority]
description = "Priority level"
schema.type = "integer"
schema.minimum = 1
schema.maximum = 5

[needs.fields.verified]
schema.type = "boolean"

```

--------------------------------

### Install Sphinx-Needs with Plotting Features

Source: https://sphinx-needs.readthedocs.io/en/stable/installation.html

Install Sphinx-Needs along with the 'plotting' extra to enable features like needbar and needpie, which require matplotlib.

```bash
pip install sphinx-needs[plotting]

```

--------------------------------

### Legacy Constraints Example

Source: https://sphinx-needs.readthedocs.io/en/stable/schema/index.html

An example of the old 'needs_constraints' dictionary format for defining validation rules.

```python
needs_constraints = {
    "security": {
        "check_0": "'security' in tags",
        "severity": "CRITICAL"
    },
    "critical": {
        "check_0": "'critical' in tags",
        "severity": "CRITICAL",
        "error_message": "need {{id}} does not fulfill CRITICAL constraint"
    }
}
```

--------------------------------

### Legacy Warnings Example

Source: https://sphinx-needs.readthedocs.io/en/stable/schema/index.html

An example of the old 'needs_warnings' dictionary format for defining validation rules.

```python
needs_warnings = {
    "invalid_status": "status not in ['open', 'closed', 'done']",
}
```

--------------------------------

### needgantt with Starts After Links

Source: https://sphinx-needs.readthedocs.io/en/stable/directives/needgantt.html

Shows the usage of `starts_after_links` to define task dependencies where a task starts after a preceding one finishes. This is a common way to model project timelines.

```directives
.. needgantt:: Starts_after example
   :tags: gantt_ex_starts_after
   :starts_after_links: starts_after

```

--------------------------------

### Full NEEDS Schema Definition Example

Source: https://sphinx-needs.readthedocs.io/en/stable/schema/index.html

This comprehensive example illustrates a full NEEDS schema file, including multiple definitions for different need types (feat, spec, impl) and various validation rules. It covers reusable definitions and specific validation logic for each type.

```json
{
  "$defs": {
    "type-feat": {
      "properties": {
        "type": { "const": "feat" }
      }
    },
    "type-spec": {
      "properties": {
        "type": { "const": "spec" }
      }
    },
    "type-impl": {
      "properties": {
        "type": { "const": "impl" }
      }
    },
    "safe-feat": {
      "allOf": [
        { "$ref": "#/$defs/safe-need" },
        { "$ref": "#/$defs/type-feat" }
      ]
    },
    "safe-spec": {
      "allOf": [
        { "$ref": "#/$defs/safe-need" },
        { "$ref": "#/$defs/type-spec" }
      ]
    },
    "safe-impl": {
      "allOf": [
        { "$ref": "#/$defs/safe-need" },
        { "$ref": "#/$defs/type-impl" }
      ]
    },
    "safe-need": {
      "properties": {
        "asil": { "enum": ["A", "B", "C", "D"] }
      },
      "required": ["asil"]
    },
    "high-efforts": {
      "properties": {
        "efforts": { "minimum": 15 }
      },
      "required": ["efforts"]
    }
  },
  "schemas": [
    {
      "severity": "warning",
      "message": "id must be uppercase with numbers and underscores",
      "validate": {
        "local": { "properties": { "id": { "pattern": "^[A-Z0-9_]+$" } } }
      }
    },
    {
      "id": "impl",
      "select": {
        "$ref": "#/$defs/type-impl"
      },
      "validate": {
        "local": {
          "properties": {
            "id": { "pattern": "^IMPL_[a-zA-Z0-9_-]*$" },
            "links": {},
            "asil": {}
          },
          "unevaluatedProperties": false
        }
      }
    },
    {
      "id": "spec",
      "select": {
        "$ref": "#/$defs/type-spec"
      },
      "validate": {
        "local": {
          "properties": {
            "id": { "pattern": "^SPEC_[a-zA-Z0-9_-]*$" },
            "efforts": { "minimum": 0, "maximum": 20 },
            "approval": {},
            "asil": {},
            "details": {}
          },
          "unevaluatedProperties": false
        }
      }
    },
    {
      "id": "feat",
      "select": {
        "$ref": "#/$defs/type-feat"
      },
      "validate": {
        "local": {
          "properties": {
            "id": { "pattern": "^FEAT_[a-zA-Z0-9_-]*$" },
            "efforts": { "minimum": 0, "maximum": 20 },
            "approval": {},
            "asil": {},
            "details": {}
          },
          "unevaluatedProperties": false
        }
      }
    },
    {
      "id": "spec-approval-required",
      "severity": "violation",
      "message": "Approval required due to high efforts",
      "select": {
        "allOf": [
          { "$ref": "#/$defs/high-efforts" },
          { "$ref": "#/$defs/type-spec" }
        ]
      },
      "validate": {
        "local": {
          "required": ["approval"]
        }
      }
    },
    {
      "id": "spec-approval-not-given",
      "severity": "warning",
      "message": "Approval not given",
      "select": {
        "allOf": [
          { "$ref": "#/$defs/type-spec" },
          { "$ref": "#/$defs/high-efforts" }
        ]
      },
      "validate": {
        "local": {
          "properties": {
            "approval": { "const": true }
          },
          "required": ["approval"]
        }
      }
    },
    {
      "id": "safe-spec-[details]->safe-feat",
      "message": "Safe spec details safe feat",
      "select": {
        "$ref": "#/$defs/safe-spec"
      },
      "validate": {
        "network": {
          "details": {
            "contains": {
              "local": {
                "$ref": "#/$defs/safe-feat"
              }
            },
            "minContains": 1,
            "maxContains": 1
          }
        }
      }
    },
    {
      "id": "safe-impl-[links]->safe-spec",
      "message": "Safe impl links to safe spec",
      "select": {
        "$ref": "#/$defs/safe-impl"
      },
      "validate": {
        "network": {
          "links": {
            "contains": {
              "local": {
                "$ref": "#/$defs/safe-spec"
              }
            },
            "minContains": 1,
            "maxContains": 1
          }
        }
      }
    }
  ]
}

```

--------------------------------

### Variant Options Example with Tags

Source: https://sphinx-needs.readthedocs.io/en/stable/dynamic_functions.html

Demonstrates setting variant options based on tags, including conditional status and a 'collapse' option.

```rst
.. req:: Variant options
   :id: VA_004
   :status: <<['variants' in tags and not collapse]:enabled, disabled>>
   :tags: variants;support
   :collapse:

   Variants for need options in action


```

--------------------------------

### New needs_fields Configuration with Defaults and Predicates

Source: https://sphinx-needs.readthedocs.io/en/stable/changelog.html

Example of the new configuration for defining fields with defaults and predicates directly on the field.

```toml
[needs.fields.status]
default = "draft"
predicates = [['status == "open"', "active"]]

```

--------------------------------

### Open-Needs Service Data Example

Source: https://sphinx-needs.readthedocs.io/en/stable/services/open_needs.html

An example structure of data retrieved from an Open-Needs service, illustrating fields like key, type, title, and options.

```json
[
   {
     "key": "NEP_001",
     "type": "Requirement",
     "title": "Build rocket",
     "description": "We finally need to build our Neptune3000 rocket.",
     "format": "txt",
     "project_id": 1,
     "options": {
       "status": "done",
       "priority": "high",
       "costs": 3500000,
       "approved": 1,
       "lastname": "Duodu"
       "firstname": "Randy"
     },
     "references": {
       "links": [
         "NEP_001",
         "NEP_002"
       ]
     }
   },
]


```

--------------------------------

### GitHub Issues Example with needservice

Source: https://sphinx-needs.readthedocs.io/en/stable/directives/needservice.html

This example demonstrates using the 'github-issues' service to query GitHub for issues in the Sphinx-Needs repository. It filters issues by content and sets an ID prefix.

```rst
.. needservice:: github-issues
   :query: repo:useblocks/sphinx-needs node latexpdf
   :max_content_lines: 4
   :id_prefix: EXAMPLE_

```

--------------------------------

### Echo Function Example

Source: https://sphinx-needs.readthedocs.io/en/stable/debug_measurement.html

Demonstrates the echo function, which returns the given string. This is primarily useful for testing purposes.

```python
A nice :ndf:`echo("first test")` for a dynamic function.
```

--------------------------------

### Parallel Execution Command Example

Source: https://sphinx-needs.readthedocs.io/en/stable/performance/script.html

Demonstrates how to use the '-j' option with sphinx-build for parallel execution. This is beneficial for projects with a large number of files.

```bash
sphinx-build -j 4 -b html . _build/html
```

--------------------------------

### Sphinx Documentation (index.rst)

Source: https://sphinx-needs.readthedocs.io/en/stable/schema/index.html

reStructuredText file defining the example need items (Feature, Specification, Implementation) with their respective fields and links.

```rst
Docs Example
============

.. feat:: Feature
   :id: FEAT_SAFE
   :asil: B

.. spec:: Specification
   :id: SPEC_SAFE
   :efforts: 20
   :approval: yes
   :asil: B
   :details: FEAT_SAFE

.. impl:: Implementation
   :id: IMPL_SAFE
   :asil: B
   :links: SPEC_SAFE


```

--------------------------------

### Deprecated needs_extra_options Configuration

Source: https://sphinx-needs.readthedocs.io/en/stable/changelog.html

Example of the old way to define extra options for needs.

```python
needs_extra_options = ["priority", "verified"]

```

--------------------------------

### New needs.fields Configuration with Schema Enum

Source: https://sphinx-needs.readthedocs.io/en/stable/changelog.html

Example of using schema enum constraints for statuses and tags.

```toml
[needs.fields.status]
schema.enum = ["draft", "approved"]

[needs.fields.tags]
schema.items.enum = ["security", "usability"]

```

--------------------------------

### Import Open-Needs Data

Source: https://sphinx-needs.readthedocs.io/en/stable/services/open_needs.html

Example of importing data from an Open-Needs server using the needservice directive with custom prefix and parameters.

```rst
.. needservice:: open-needs
   :prefix: ONS_
   :params: skip=0;limit=10


```

--------------------------------

### Import GitHub Issue Example

Source: https://sphinx-needs.readthedocs.io/en/stable/services/github.html

This snippet demonstrates how to import a GitHub issue using the `needservice` directive with basic query parameters.

```rst
.. needservice:: github-issues
   :query: repo:useblocks/sphinx-needs node latexpdf
   :max_amount: 1
   :max_content_lines: 4


```

--------------------------------

### Configuring Multiple Service Instances

Source: https://sphinx-needs.readthedocs.io/en/stable/services/index.html

Example of configuring multiple instances of the same service with different settings in `conf.py`. This is useful for connecting to different servers or using distinct configurations.

```python
from sphinx_needs.services.xy import NeededService

needs_services = {
    'my-company-service': {
        'class': NeededService,
        'class_init': {
            # ...
        },
        # ...
    }
}


```

--------------------------------

### Build Sphinx-Needs HTML Documentation

Source: https://sphinx-needs.readthedocs.io/en/stable/contributing.html

Build the HTML documentation using the furo theme. The CLEAN=true flag ensures old build files are removed before building.

```bash
# Build HTML pages with the furo theme,
# and first remove all old build files
CLEAN=true tox -e docs-furo
```

--------------------------------

### Custom Need Item with Options

Source: https://sphinx-needs.readthedocs.io/en/stable/tutorial.html

Shows how to create a custom need item using the 'tutorial-project' directive. Includes optional fields like tags, layout, image, and collapse for richer item representation.

```rst
.. tutorial-project:: Our new car
    :id: T_CAR
    :tags: tutorial
    :layout: clean_l
    :image: _images/car.png
    :collapse: true

    Presenting the “TeenTrek,” an autonomous driving car tailored for teenagers without a driving license.
    Equipped with advanced AI navigation and safety protocols, it ensures effortless and secure transportation.
    The interior boasts entertainment systems, study areas, and social hubs, catering to teen preferences.
    The TeenTrek fosters independence while prioritizing safety and convenience for young passengers.


```

--------------------------------

### Schema Violation Report JSON Example

Source: https://sphinx-needs.readthedocs.io/en/stable/schema/index.html

An example structure of the JSON file detailing schema validation outcomes, including warnings and summary statistics.

```json
{
  "validation_summary": "Schema validation completed with 2 warning(s) in 0.002 seconds. Validated 1368 needs/s.",
  "validated_needs_per_second": 1368,
  "validated_needs_count": 3,
  "validation_warnings": {
    "FEAT_unsafe": [
      {
        "log_lvl": "warning",
        "type": "sn_schema",
        "subtype": "local_fail",
        "details": {
          "severity": "violation",
          "field": "id",
          "need_path": "FEAT_unsafe",
          "schema_path": "[0] > local > properties > id > pattern",
          "user_msg": "id must be uppercase with numbers and underscores",
          "validation_msg": "'FEAT_unsafe' does not match '^[A-Z0-9_]+$'"
        },
        "children": []
      }
    ],
    "IMPL_SAFE": [
      {
        "log_lvl": "warning",
        "type": "sn_schema",
        "subtype": "network_local_fail",
        "details": {
          "severity": "violation",
          "field": "asil",
          "need_path": "IMPL_SAFE > links > SPEC_UNSAFE",
          "schema_path": "safe-impl-[links]->safe-spec[7] > links > local > allOf > 0 > properties > asil > enum",
          "validation_msg": "'QM' is not one of ['A', 'B', 'C', 'D']"
        },
        "children": []
      }
    ]
  }
}
```

--------------------------------

### Apply Multiple Configurations to Needflow

Source: https://sphinx-needs.readthedocs.io/en/stable/directives/needflow.html

This example demonstrates applying multiple configurations ('monochrome', 'lefttoright', 'handwritten') to a needflow, separated by commas. It also includes filtering and link type specifications.

```rst
.. needflow::
   :filter: is_need
   :tags: flow_example
   :types: spec
   :link_types: tests, blocks
   :show_link_names:
   :config: monochrome,lefttoright,handwritten


```

--------------------------------

### Defining Specification Need Items with Links

Source: https://sphinx-needs.readthedocs.io/en/stable/tutorial.html

Illustrates defining specification need items (e.g., .. tutorial-spec::) and linking them using a custom 'specifies' relationship, demonstrating how to connect requirements to their implementations.

```rst
.. tutorial-spec:: Implement RADAR system
   :id: T_RADAR
   :tags: tutorial
   :tutorial_specifies: T_SAFE

   The RADAR sensor software for the car must accurately detect and track surrounding objects
   within a specified range. It should employ signal processing algorithms to filter out noise
   nd interference, ensuring reliable object detection in various weather and road conditions.
   The software should integrate seamlessly with the car's control system, providing real-time
   data on detected objects to enable collision avoidance and adaptive cruise control functionalities.
   Additionally, it should adhere to industry standards for safety and reliability, with robust
   error handling mechanisms in place.


.. tutorial-spec:: Implement distant detection
   :id: T_DIST
   :tags: tutorial
   :tutorial_specifies: T_SAFE

   Software Specification for Distance Detection Algorithm.
```

--------------------------------

### needgantt with Starts With Links

Source: https://sphinx-needs.readthedocs.io/en/stable/directives/needgantt.html

Illustrates how to use the `starts_with_links` option to define task relationships where one task begins after another. This is useful for sequential task dependencies.

```directives
.. needgantt:: Starts_with example
   :tags: gantt_ex_starts_with
   :starts_with_links: starts_with

```

--------------------------------

### Nested Conditional Link Example

Source: https://sphinx-needs.readthedocs.io/en/stable/directives/need.html

Provides an example of a condition that itself contains square brackets, demonstrating how to handle nested conditions, such as accessing list elements.

```rst
REQ_001[[tags[0]=="important"]]

```

--------------------------------

### Requirement with Permalink

Source: https://sphinx-needs.readthedocs.io/en/stable/layout_styles.html

Demonstrates a requirement using the 'permalink_example' layout, which displays a permalink icon next to the ID.

```python
.. req:: A requirement with a permalink
   :id: EX_REQ_5
   :tags: example
   :status: open
   :layout: permalink_example

   This is like a normal requirement looks like but additionally a permalink icon is shown next to the ID.

```

--------------------------------

### New Format for Global Options

Source: https://sphinx-needs.readthedocs.io/en/stable/configuration.html

Demonstrates the current, more explicit format for setting global options with defaults and predicates.

```python
needs_global_options = {
    "field1": {"default": "a"},
    "field2": {"predicates": [('status == "done"', "a")]},
    "field3": {
        "predicates": [('status == "done"', "a")],
        "default": "b",
    },
    "field4": {
        "predicates": [
            ('status == "done"', "a"),
            ('status == "ongoing"', "b"),
            ('status == "other"', "c"),
        ],
        "default": "d",
    },
}
```

--------------------------------

### Multiple Checks and Joint Status Example

Source: https://sphinx-needs.readthedocs.io/en/stable/debug_measurement.html

Shows how multiple checks can be performed, and their positive results are joined. This example checks for 'in progress' status with 'one_hit=True' and 'closed' status with 'one_hit=True'.

```python
.. spec:: result 5: Two checks and a joint status
:links: clv_A, clv_B, clv_C
:status: [[check_linked_values('progress', 'status', 'in progress', one_hit=True )]] [[check_linked_values('closed', 'status', 'closed', one_hit=True )]]
:collapse: False
```

--------------------------------

### Generate ID from Title Example

Source: https://sphinx-needs.readthedocs.io/en/stable/configuration.html

When `needs_id_from_title` is `True` and no user-defined ID is provided, Sphinx-Needs generates an ID based on the need's prefix, title, and a hashed value. This example demonstrates the expected output format.

```rst
.. req:: Group big short

```

--------------------------------

### Dynamic Image Layout Line

Source: https://sphinx-needs.readthedocs.io/en/stable/layout_styles.html

Demonstrates using a layout function with dynamic arguments based on need options. This example uses the `author` option to construct an image path.

```rst
'<<image("_images/{{author}}.png", align="center")>>'

```

--------------------------------

### NeedArch Loop Detection Example

Source: https://sphinx-needs.readthedocs.io/en/stable/directives/needarch.html

This example showcases `needarch`'s ability to detect and handle include loops. It uses Jinja logic with `flow()` and conditional `uml()` calls to manage dependencies and prevent duplicate rendering of needs, even with different parameter sets.

```rst
.. comp:: COMP_T_001
   :id: COMP_T_001

   .. needarch::

      {{flow(need().id)}}
      {% if variant == "A" %}
      {{uml('COMP_T_003', variant="A")}}
      usecase {{need().id}}_usecase
      {% else %}
      {{uml('COMP_T_003')}}
      {{uml('COMP_T_003', variant="A")}}
      {% endif %}

.. comp:: COMP_T_002
   :id: COMP_T_002

   .. needarch::

      {{flow(need().id)}}
      {% if variant == "A" %}
      {{uml('COMP_T_001', variant="A")}}
      usecase {{need().id}}_usecase
      {% else %}
      {{uml('COMP_T_001')}}
      {% endif %}

.. comp:: COMP_T_003
   :id: COMP_T_003

   .. needarch::

      {{flow(need().id)}}
      {% if variant == "A" %}
      {{uml('COMP_T_002', variant="A")}}
      usecase {{need().id}}_usecase
      {% else %}
      {{uml('COMP_T_002')}}
      {% endif %}


```

--------------------------------

### Build Documentation with Linkcheck Builder

Source: https://sphinx-needs.readthedocs.io/en/stable/contributing.html

Build the documentation and check for broken links using the linkcheck builder. The CLEAN=true flag ensures old build files are removed.

```bash
# Check links in the documentation
CLEAN=true BUILDER=linkcheck tox -e docs-furo
```

--------------------------------

### Importing Needs from Absolute Path (Windows)

Source: https://sphinx-needs.readthedocs.io/en/stable/directives/needimport.html

Illustrates importing needs from an absolute path on Windows systems using standard drive letters.

```rst
.. needimport:: c:/absolute/path/to/needs.json

```

```rst
.. needimport:: c:\absolute\path\to\needs.json

```

--------------------------------

### New needs.fields Configuration for Variant Parsing

Source: https://sphinx-needs.readthedocs.io/en/stable/changelog.html

Example of enabling variant parsing per-field.

```toml
[needs.fields.author]
parse_variants = true

[needs.fields.status]
parse_variants = true

```

--------------------------------

### Build with the 'needs' builder

Source: https://sphinx-needs.readthedocs.io/en/stable/builders.html

Use this command to build your documentation with the 'needs' builder, which exports needs to a JSON file.

```bash
sphinx-build -b needs source_dir build_dir

```

--------------------------------

### Deprecated needs_variant_options Configuration

Source: https://sphinx-needs.readthedocs.io/en/stable/changelog.html

Example of the old way to enable variant parsing globally.

```python
needs_variant_options = ["author", "status"]

```

--------------------------------

### View Available Tox Environments

Source: https://sphinx-needs.readthedocs.io/en/stable/contributing.html

Use tox to manage testing and documentation building environments. This command lists all available environments.

```bash
tox -av
```

--------------------------------

### Deprecated needs_extra_links Configuration

Source: https://sphinx-needs.readthedocs.io/en/stable/changelog.html

Example of the old way to define extra links for needs.

```toml
[[needs.extra_links]]
option = "blocks"
incoming = "is blocked by"

```

--------------------------------

### Deprecated needs_statuses and needs_tags Configuration

Source: https://sphinx-needs.readthedocs.io/en/stable/changelog.html

Example of the old way to define allowed statuses and tags.

```python
needs_statuses = [{name = "draft"}, {name = "approved"}]
needs_tags = [{name = "security"}, {name = "usability"}]

```

--------------------------------

### Full ubproject.toml Configuration for Needs

Source: https://sphinx-needs.readthedocs.io/en/stable/schema/index.html

This snippet shows a comprehensive example of the ubproject.toml configuration for the 'needs' feature, including schema definitions, field configurations, and type definitions.

```toml
$schema = "https://ubcode.useblocks.com/ubproject.schema.json"

[needs]
id_required = true
id_regex = "^[A-Z0-9_]{3,}$"
build_json = true
schema_definitions_from_json = "schemas.json"
schema_debug_active = true
# schema_debug_ignore = []

[needs.fields.efforts]
description = "FTE days"
schema.type = "integer"
schema.minimum = 0

[needs.fields.asil]
description = "Automotive Safety Integrity Level"
schema.type = "string"
schema.enum = ["QM", "A", "B", "C", "D"]

[needs.fields.approval]
description = "Approval flag"
schema.type = "boolean"

[needs.links.links]
outgoing = "links"
incoming = "linked by"
schema.maxItems = 1

[needs.links.details]
outgoing = "details"
incoming = "detailed by by"
schema.maxItems = 1

[[needs.types]]
directive = "feat"
title = "Feat"
prefix = "Feat_"

[[needs.types]]
directive = "spec"
title = "Specification"
prefix = "SPEC_"

[[needs.types]]
directive = "impl"
title = "Implementation"
prefix = "IMPL_"

# link modeling impl -[links]-> spec -[details]-> feat

```

--------------------------------

### Negative check_linked_values Example

Source: https://sphinx-needs.readthedocs.io/en/stable/dynamic_functions.html

Status is not set to 'progress' because linked need 'clv_C' does not match 'in progress'.

```rst
.. spec:: result 2: Negative check
   :links: clv_A, clv_B, clv_C
   :status: [[check_linked_values('progress', 'status', 'in progress' )]]
   :collapse: False

```

--------------------------------

### Copy Need Option Example

Source: https://sphinx-needs.readthedocs.io/en/stable/debug_measurement.html

Demonstrates copying a need option to another need. It shows how to copy status and ID, and how to use dynamic values within filter strings.

```python
.. req:: copy-example
:id: copy_1
:tags: tag_1, tag_2, tag_3
:status: open

.. spec:: copy-example implementation
:id: copy_2
:status: [[copy("status", "copy_1")]]
:links: copy_1
:comment: [[copy("id")]]

Copies status of ``copy_1`` to own status.
Sets also a comment, which copies the id of own need.

.. test:: test of specification and requirement
:id: copy_3
:links: copy_2; [[copy('links', 'copy_2')]]
:tags: [[copy('tags', 'copy_1')]]

Set own link to ``copy_2`` and also copies all links from it.

Also copies all tags from copy_1.

If the filter_string needs to compare a value from the current need and the value is unknown yet,
you can reference the valued field by using ``current_need["my_field"]`` inside the filter string.
Small example::

.. test:: test of current_need value
:id: copy_4

The following copy command copies the title of the first need found under the same highest
section (headline):

:ndf:`copy('title', filter='current_need["sections"][-1]==sections[-1]')`

.. test:: test of current_need value
:id: copy_4

The following copy command copies the title of the first need found under the same highest
section (headline):

:ndf:`copy('title', filter='current_need["sections"][-1]==sections[-1]')`
```

--------------------------------

### Input Needs for check_linked_values

Source: https://sphinx-needs.readthedocs.io/en/stable/dynamic_functions.html

Defines the input needs (requirements and specifications) used in the examples for the check_linked_values function.

```rst
.. req:: Input A
   :id: clv_A
   :status: in progress

.. req:: Input B
   :id: clv_B
   :status: in progress

.. spec:: Input C
   :id: clv_C
   :status: closed

```

--------------------------------

### needservice Directive with Options and Content

Source: https://sphinx-needs.readthedocs.io/en/stable/services/index.html

This example shows how to use the `needservice` directive with specific options like tags, status, and author, and also includes custom content that will be added to the created needs.

```rst
.. needservice:: <service_name>
   :tags: awesome, nice, cool
   :status: open
   :author: me

   My **custom** content.


```

--------------------------------

### Filter by type and status

Source: https://sphinx-needs.readthedocs.io/en/stable/filter.html

Example of a filter string to count needs where the type is 'spec' and the status is not 'open'.

```rst
:need_count:`type=='spec' and status != 'open'`


```

--------------------------------

### Basic Custom Service Implementation

Source: https://sphinx-needs.readthedocs.io/en/stable/services/index.html

Implement a custom service by inheriting from BaseService and defining the request method. The request method should return a list of dictionaries representing needs. The __init__ method can access configuration values.

```python
from sphinx_needs.services.base import BaseService

class MyService(BaseService):

    def __init__(self, app, name, config, **kwargs):
        # Get a config value from service related part
        # of needs_services inside conf.py
        self.my_config = config.get('my_config', 'DEFAULT')

        # Custom init config, which is provided only once
        # during class initialisation
        custom_init =  kwargs.get('custom_init', False)

        super(GithubService, self).__init__()

    def request(self, options):
        # Get an option provided by the user in the directive call
        status = options.get('status', 'Unknown')

        data = [
            {
                'title': 'My Issue 1',
                'status': status,
                'my_config': self.my_config
            },
            {
                'title': 'My Issue 2',
                'type': 'spec'
            }
        ]

        return data

    def debug(self, options):
        # Allows to send back data, which may be helpful for debugging.
        # debug_data needs do be serializable via json.dump.()
        debug_data = {'custom_debug': 'data'}
        return debug_data

```

--------------------------------

### Setting Global Defaults with needs_fields

Source: https://sphinx-needs.readthedocs.io/en/stable/configuration.html

Example of setting global defaults for tags and a specific needs_field using needs_global_options.

```python
needs_fields = {"option1": {}}
needs_global_options = {
   "tags": {"default": ["tag1", "tag2"]},
   "option1": {"default": "new value"},
}
```

--------------------------------

### Configure GitHub Enterprise Instance

Source: https://sphinx-needs.readthedocs.io/en/stable/services/github.html

Shows how to configure Sphinx-Needs to connect to a GitHub Enterprise instance. This involves specifying the service class, URL, authentication credentials, and other service-specific options.

```python
from sphinx_needs.services.github import GithubService

needs_services = {
    # Cloud GitHub configuration
    'github-issues': {
        'max_content_lines': 20,
        'id_prefix': 'GH_ISSUE_',
    },
    # GitHub Enterprise configuration
    'my-company-issues': {
        'class': GithubService,
        'class_init': {
            'gh_type': 'issue'
        },
        'url': 'https://github.my-company.com/api/v3/',
        'username': 'my_username',
        'token':  'my_github_token',
        'download_avatars': True,
        'download_folder': 'company-avatars',
        'max_content_lines': 20,
        'id_prefix': 'COMPANY_ISSUE_',
    }
}


```

--------------------------------

### Deprecated needs_global_options Configuration

Source: https://sphinx-needs.readthedocs.io/en/stable/changelog.html

Example of the old way to set global options for fields, including defaults and predicates.

```toml
[needs.global_options.status]
default = "draft"
predicates = [['status == "open"', "active"]]

```

--------------------------------

### Defining Numeric Field Schema

Source: https://sphinx-needs.readthedocs.io/en/stable/changelog.html

Example of defining a 'version' field with an 'integer' schema type in Sphinx-Needs configuration.

```ini
[needs.fields.version]
schema.type = "integer"
nullable = false


```

--------------------------------

### Importing Needs from Absolute Path (Linux/OSX)

Source: https://sphinx-needs.readthedocs.io/en/stable/directives/needimport.html

Shows how to import needs from an absolute path on Linux or macOS systems by prefixing with two slashes.

```rst
.. needimport:: //absolute/path/to/needs.json

```

--------------------------------

### Basic Requirement Directive

Source: https://sphinx-needs.readthedocs.io/en/stable/layout_styles.html

A simple example of the .. req:: directive to define a basic requirement with an ID and status.

```python
.. req:: A normal requirement
   :id: EX_REQ_1
   :status: open

   This is how a normal requirement looks like

```

--------------------------------

### Positive check_linked_values Example

Source: https://sphinx-needs.readthedocs.io/en/stable/dynamic_functions.html

Sets the status to 'progress' when linked needs 'clv_A' and 'clv_B' have the status 'in progress'.

```rst
.. spec:: result 1: Positive check
   :links: clv_A, clv_B
   :status: [[check_linked_values('progress', 'status', 'in progress' )]]
   :collapse: False

```

--------------------------------

### Project Configuration (ubproject.toml)

Source: https://sphinx-needs.readthedocs.io/en/stable/schema/index.html

TOML configuration file for the project, specifying schema definitions, ID requirements, and JSON build settings.

```toml
"$schema" = "https://ubcode.useblocks.com/ubproject.schema.json"

[needs]
id_required = true
id_regex = "^[A-Z0-9_]{3,} "
build_json = true
schema_definitions_from_json = "schemas.json"
schema_debug_active = true

```

--------------------------------

### Basic needpie Chart

Source: https://sphinx-needs.readthedocs.io/en/stable/directives/needpie.html

A basic example of the needpie directive. It uses a title and filters needs based on type.

```rst
.. needpie:: My pie chart

   type == 'req'
   type == 'spec'
   10

```

--------------------------------

### Defining Need Items with Custom Links

Source: https://sphinx-needs.readthedocs.io/en/stable/tutorial.html

Shows how to define need items using custom directives (e.g., .. tutorial-req::) and link them using the custom link type defined in conf.py (e.g., :tutorial_required_by:).

```rst
.. tutorial-req:: Safety Features
   :id: T_SAFE
   :tags: tutorial
   :tutorial_required_by: T_CAR

   The car must include advanced safety features such as automatic braking, collision avoidance systems, and adaptive cruise control to ensure the safety of teenage drivers.

.. tutorial-req:: Connectivity and Entertainment
   :id: T_CONNECT
   :tags: tutorial
   :tutorial_required_by: T_CAR

   The car should be equipped with built-in Wi-Fi, Bluetooth connectivity, and compatibility with smartphone integration systems to enable seamless communication and entertainment for teenagers on the go.
```

--------------------------------

### Full needbar Chart with All Options

Source: https://sphinx-needs.readthedocs.io/en/stable/directives/needbar.html

Demonstrates the use of all available options for the needbar directive, including legend, colors, text color, style, axis titles, labels, and stacking.

```rst
.. needbar:: Full bar chart
   :legend:
   :colors: #ffcc88, #ffcc00, #444444
   :text_color: crimson
   :style: dark_background
   :x_axis_title: x_axis_title
   :xlabels_rotation: 90
   :xlabels: a, b, c
   :y_axis_title: y_axis_title
   :ylabels: FROM_DATA
   :ylabels_rotation: 45
   :separator: ;
   :stacked:
   :show_top_sum:
   :show_sum:
   :sum_rotation: 90
   :transpose:
   :horizontal:

   Z; 5;20;15
   Y;10;15;10
   X;15;10;20
   W;20;15;10


```

--------------------------------

### check_linked_values with one_hit=True Example

Source: https://sphinx-needs.readthedocs.io/en/stable/dynamic_functions.html

Status is set to 'progress' because 'one_hit' is True, requiring only one linked need to match the criteria.

```rst
.. spec:: result 4: Positive check thanks of one_hit option
   :links: clv_A, clv_B, clv_C
   :status: [[check_linked_values('progress', 'status', 'in progress', one_hit=True )]]
   :collapse: False

```

--------------------------------

### Customizing Need Layout with :layout:

Source: https://sphinx-needs.readthedocs.io/en/stable/directives/need.html

Demonstrates how to use the `:layout:` directive option to apply specific grid and content mappings for a need. Different layout values like 'clean', 'complete', and 'focus' can be used.

```rst
.. req:: My layout requirement 1
   :id: LAYOUT_1
   :tags: layout_example
   :layout: clean

   Some **content** of LAYOUT_1

```

```rst
.. req:: My layout requirement 2
   :id: LAYOUT_2
   :tags: layout_example
   :layout: complete

   Some **content** of LAYOUT_2

```

```rst
.. req:: My layout requirement 3
   :id: LAYOUT_3
   :tags: layout_example
   :layout: focus

   Some **content** of LAYOUT_3

```

--------------------------------

### check_linked_values with Filter Example

Source: https://sphinx-needs.readthedocs.io/en/stable/dynamic_functions.html

Status is set to 'progress' because 'clv_C' is excluded by the filter 'type == "req"'.

```rst
.. spec:: result 3: Positive check thanks of used filter
   :links: clv_A, clv_B, clv_C
   :status: [[check_linked_values('progress', 'status', 'in progress', 'type == "req" ' )]]
   :collapse: False

```

--------------------------------

### Basic needtable with tags filter

Source: https://sphinx-needs.readthedocs.io/en/stable/directives/needtable.html

Generates a table of needs filtered by the 'main_example' tag, using the default table style.

```rst
.. needtable:: Example table
   :tags: main_example
   :style: table


```

--------------------------------

### Importing Needs from a Local Path

Source: https://sphinx-needs.readthedocs.io/en/stable/directives/needimport.html

Illustrates importing needs from a JSON file using a local path relative to the containing document.

```rst
.. needimport:: needs.json

```

--------------------------------

### Filter needs on the current page

Source: https://sphinx-needs.readthedocs.io/en/stable/filter.html

Example of using the `c.this_doc()` function to filter a needtable for needs only within the current document.

```rst
.. needtable::
   :filter: c.this_doc()
   :style: datatables


```

--------------------------------

### Conditional Link Example

Source: https://sphinx-needs.readthedocs.io/en/stable/directives/need.html

Demonstrates how to link to a requirement only if its status is 'open'. The condition is evaluated against the target need's attributes.

```rst
.. spec:: My Specification
   :links: REQ_001[status=="open"]


```

--------------------------------

### Help for Test Series Parameters

Source: https://sphinx-needs.readthedocs.io/en/stable/performance/script.html

Displays available options for customizing the performance test series, such as setting the number of needs, needtables, dummies, pages, and parallel cores.

```shell
python performance_test.py series --help
```
Tokens:
Raw