Support default values for options per file

It would be nice to specify need option values not only globally but per file as well.

The default option values is currently available on a per-project basis in sphinx-needs:

needs_global_options = {
      'my_option': 'my_global_value'
}

However, in big projects, requirements with different “standard options” exist, and per-file grouping is a natural strategy to structure them. In projects with some mandatory requirements attributes, repeated options lead to visual noise (repetitive content repeated a lot with little additional information).

Now:

.. need:: 
   :id: NEED_ID_1
   :my_option: same_value
   :some-other-option: value1

.. need:: 
   :id: NEED_ID_2
   :my_option: same_value
   :some-other-option: value2

.. need:: 
   :id: NEED_ID_3
   :my_option: same_value
   :some-other-option: value2

Later:

.. needoptions:
  :my_option: same_value

.. need:: 
   :id: NEED_ID_2
   :some-other-option: value1

.. need:: 
   :id: NEED_ID_2
   :some-other-option: value2

.. need:: 
   :id: NEED_ID_3
   :some-other-option: value2

The needoptions shall apply to all needs in the current page starting where the directive appears. Probably there could be a filter option as well to filter certain need types (within the page).

Idea came from @arwedus 😃

[danwos]

Good points and I agree. conf.py should not be too related to the internal documentation structure.

I also thought that your case is somehow related to inheritance.

Here is an idea:

Need can inherit from any other need

.. need:: My basic need
   :id: basic_001
   :status: open
   :tags: tag_01
   :hide: true
   
.. need:: Another need
   :id: REAL_NEED_001
   :tags: my_tag
   :inherit: basic_001     

REAL_NEED_001 will have status: open and tags: my_tag.

The user can decide, if a need like basic_001 shall be shown or gets hidden. basic_001 could also get automatically inherited_from: True as option, so that all needs which are used for inheritance could get the hide-option automatically via needs_global_options.

This somehow feels like needextend, but only the other way around.

Beside the overall inheritance idea, wouldn’t needextend be a solution for your case?

.. needextend:: docname == "this_page.rst"
  :my_option: same_value

.. need:: 
   :id: NEED_ID_2
   :some-other-option: value1

.. need:: 
   :id: NEED_ID_2
   :some-other-option: value2

.. need:: 
   :id: NEED_ID_3
   :some-other-option: value2

[danwos]

Regarding the correct docname, you can check the set value by using the debug layout in one of your need objects:

.. dod::  An example
   :id: DOD_001
   :layout: debug 

Docs: https://sphinxcontrib-needs.readthedocs.io/en/latest/layout_styles.html#EX_DEBUG This shows you also all the other option values.

In your case I think the correct one is work_products/software_wp/sw_req_eng_wp/sw_requirements_specification_wp, without the file extension.