### Setup Pre-commit Hooks Source: https://github.com/useblocks/sphinx-needs/blob/master/tests/doc_test/broken_links/contributing.md Install pre-commit to automatically run formatting and linting checks on every commit. Use --all-files to run manually across the entire project. ```bash pre-commit install ``` ```bash pre-commit run --all-files ``` -------------------------------- ### Install Sphinx-Needs from source Source: https://github.com/useblocks/sphinx-needs/blob/master/README.rst Clones the repository and installs the package locally. ```bash git clone https://github.com/useblocks/sphinx-needs cd sphinx-needs pip install . ``` -------------------------------- ### Install development dependencies Source: https://github.com/useblocks/sphinx-needs/blob/master/tests/doc_test/add_sections_sigs/contributing.md Use these commands to install required packages for testing, benchmarking, and documentation. ```bash pip install sphinx-needs[test,benchmark,docs] ``` ```bash uv sync ``` -------------------------------- ### Install Sphinx-Needs via pip Source: https://github.com/useblocks/sphinx-needs/blob/master/README.rst Standard installation command for the package. ```bash pip install sphinx-needs ``` -------------------------------- ### Install Documentation Requirements Source: https://github.com/useblocks/sphinx-needs/blob/master/docs/contributing.md Install the Python dependencies required for building the official documentation. This is a prerequisite for certain documentation tasks. ```bash pip install -r docs/requirements.txt ``` -------------------------------- ### Gantt Chart Task Dependency Example Source: https://github.com/useblocks/sphinx-needs/blob/master/tests/doc_test/doc_global_options/directives/needgantt.md Demonstrates how to set a task to start after another specific task using the 'starts after' option in the needgantt directive. Ensure the referenced task ID exists. ```rst .. needgantt:: Starts after example :tags: gantt_ex_starts_after :starts_after: [ACT_CREATE_EX_SA](#ACT_CREATE_EX_SA) ``` -------------------------------- ### Run Sphinx Build Command Source: https://github.com/useblocks/sphinx-needs/blob/master/docs/schema/index.md Execute this command to build the documentation with the schema example. ```default tests/doc_test/doc_schema_example $ uv run sphinx-build -b html . _build ``` -------------------------------- ### Display a flow diagram of need items Source: https://github.com/useblocks/sphinx-needs/blob/master/docs/tutorial.md Use the `needflow` directive to display a flow diagram of need items, showing relationships. This example visualizes the 'Engineering plan to develop a car' starting from 'T_CAR', with custom border colors based on status. ```rst .. needflow:: Engineering plan to develop a car :alt: Engineering plan to develop a car :root_id: T_CAR :config: lefttoright,tutorial :show_link_names: :border_color: [status == 'open']:FF0000, [status == 'in progress']:0000FF, [status == 'closed']:00FF00 ``` -------------------------------- ### Verify Cypress installation Source: https://github.com/useblocks/sphinx-needs/blob/master/tests/doc_test/add_sections_sigs/contributing.md Ensure Cypress is correctly installed and executable. ```bash npx cypress verify ``` -------------------------------- ### Build documentation Source: https://github.com/useblocks/sphinx-needs/blob/master/tests/doc_test/add_sections_sigs/contributing.md Commands to build HTML documentation or verify links. ```bash # Build HTML pages with the furo theme, # and first remove all old build files CLEAN=true tox -e docs-furo ``` ```bash # Check links in the documentation CLEAN=true BUILDER=linkcheck tox -e docs-furo ``` -------------------------------- ### Snakeviz Installation Source: https://github.com/useblocks/sphinx-needs/blob/master/docs/performance/script.md Command to install the snakeviz tool for profile analysis. ```bash pip install snakeviz ``` -------------------------------- ### Build Documentation with Different Themes using Tox Source: https://github.com/useblocks/sphinx-needs/blob/master/AGENTS.md Build the documentation using various themes by specifying different tox environments. This helps in checking theme compatibility. ```bash tox -e docs-alabaster tox -e docs-rtd tox -e docs-pds tox -e docs-im ``` -------------------------------- ### Example: Sphinx-Needs String Links Configuration Source: https://github.com/useblocks/sphinx-needs/blob/master/tests/doc_test/doc_needuml_save/configuration.md This example demonstrates how to configure `needs_string_links` in `conf.py` to create links to Sphinx-Needs documentation and GitHub issues. ```python # conf.py needs_string_links = { # Adds link to the Sphinx-Needs configuration page 'config_link': { 'regex': r'^(?P\w+)$', 'link_url': 'https://sphinx-needs.readthedocs.io/en/latest/configuration.html#{{value | replace("_", "-")}}', 'link_name': 'Sphinx-Needs docs for {{value | replace("_", "-") }}\\n 'options': ['config'] }, # Links to the related github issue 'github_link': { 'regex': r'^(?P\w+)$', 'link_url': 'https://github.com/useblocks/sphinx-needs/issues/{{value}}', 'link_name': 'GitHub #{{value}}', 'options': ['github'] } } ``` -------------------------------- ### needlist Examples Source: https://github.com/useblocks/sphinx-needs/blob/master/tests/doc_test/doc_complex/directives/needlist.md Illustrative examples of using the needlist directive with different options. ```APIDOC ## needlist Directive Examples ### Example 1: Basic Usage with Tags ```rst .. needlist:: :tags: main_example ``` ### Example 2: Showing Status and Filtering by Status ```rst .. needlist:: :show_status: :status: done; implemented ``` ### Example 3: Showing Tags and Filtering by Status ```rst .. needlist:: :show_tags: :status: done; implemented ``` ### Example 4: Showing Filters Used ```rst .. needlist:: :show_filters: :status: done; implemented ``` ### Common Filters - [status](../filter.md#option-status) - [tags](../filter.md#option-tags) - [types](../filter.md#option-types) - [filter](../filter.md#option-filter) ``` -------------------------------- ### Build Sphinx-Needs Documentation with Furo Theme Source: https://github.com/useblocks/sphinx-needs/blob/master/docs/contributing.md Build the HTML documentation using the furo theme. The CLEAN=true flag ensures that old build files are removed before building. ```bash CLEAN=true tox -e docs-furo ``` -------------------------------- ### Schema Path Examples Source: https://github.com/useblocks/sphinx-needs/blob/master/docs/schema/index.md Examples of schema path identifiers used in validation error reporting. ```default [0] > local > properties > id > pattern spec[1] > local > properties > id > pattern ``` -------------------------------- ### Example: Jinja Content in Needs Source: https://github.com/useblocks/sphinx-needs/blob/master/docs/configuration.md Demonstrates how to enable and use Jinja templating within need descriptions, including aliases and dynamic content. ```APIDOC ## Example: Need with jinja_content enabled ### Description This example shows a need with the `jinja_content` option enabled, allowing for dynamic content rendering using Jinja variables and loops. ### Directive ```rst .. req:: Need with jinja_content enabled :id: JINJA1D8913 :jinja_content: true Need with alias {{ custom_data_1 }} and ``jinja_content`` option set to {{ custom_data_3 }}. {{ custom_data_2 }} {% for author in custom_data_4 %} * {{ author[0] }} + {{ author[1] }} {% endfor %} ``` ### Rendered Output Example | Requirement: **Need with jinja_content enabled** [JINJA1D8913](#JINJA1D8913)

| |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |


| | Need with alias Project_X and `jinja_content` option set to true.

List of contributors:

* Daniel
+ 811982
* Marco
+ 234232 | ```