Documentation

Here we want to show how to have the same element multiple times in the Documentation.

Howto:

You do have to patch your conf.py to get this working:

Changes in conf.py

# define configuration
# patching of links is been need for useblocks sphinx-test-reports
needs_id_prefixes = [
    {
    "postfix": "",
    "prefix":  "A_",
    "prefix_after_type": True,
    "paths": ["components/A/"],
    "links": ["satisfies", "links",],
    },
    {
    "postfix": "_B",
    "prefix":  "",
    "prefix_after_type": False,
    "paths": ["components/B/"],
    "links": ["satisfies", "links",],
    },
    {
    "postfix": "",
    "prefix":  "C_",
    "prefix_after_type": False,
    "paths": ["components/C/"],
    "links": ["satisfies", "links",],
    },
]

# validate that paths not overlap each other
for i in range(len(needs_id_prefixes)):
    for j in range(len(needs_id_prefixes)):
        if i != j:
            i_paths = needs_id_prefixes[i]["paths"]
            j_paths = needs_id_prefixes[i]["paths"]
            for k in range(len(i_paths)):
                for l in range(len(j_paths)):
                    if k != l:
                        overlap: bool = False
                        overlap = overlap or i_paths[k].startswith(j_paths[l])
                        overlap = overlap or j_paths[l].startswith(i_paths[k])
                        if overlap:
                            print("Warning: in needs_id_prefixes")
                            print("It is not allowed to have overlapping 'paths': " + i_paths[k] + " " + j_paths[l])

# patch NeedCheckContext

from sphinx_needs.filter_common import NeedCheckContext


NeedCheckContext.needs_id_prefixes = needs_id_prefixes

def this_prefix(self) -> bool:
    if self._origin_docname is None:
        raise ValueError("`this_doc` can not be used in this context")

    result: bool = False
    check_any_prefix_match_current_file: bool = False
    check_any_prefix_match_current_need: bool = False
    for needs_id_prefix in needs_id_prefixes:
        for path in needs_id_prefix['paths']:
            result = result or \
                (self._origin_docname.startswith(path) and self._need["docname"].startswith(path))
            check_any_prefix_match_current_file = check_any_prefix_match_current_file or \
                self._origin_docname.startswith(path)
            check_any_prefix_match_current_need = check_any_prefix_match_current_need or \
                self._need["docname"].startswith(path)

    if check_any_prefix_match_current_file:
        return result
    else:
        # The current file does not fit in any prefix area
        # -> Return True if need is even not part of any prefix area
        return not check_any_prefix_match_current_need

NeedCheckContext.this_prefix = this_prefix

#function to patch ids
def patch_id(id:str, config: dict):
    new_id: str = ""

    if "prefix" in config:
        patched: bool = False
        if "prefix_after_type" in config and config["prefix_after_type"]:
            for type_prefix in config['type_prefixes']:
                if id.startswith(type_prefix):
                    id_without_type_prefix:str = id[len(type_prefix):]
                    new_id = type_prefix + config["prefix"] + id_without_type_prefix
                    patched = True
                    break

        if not patched:
            new_id = config["prefix"] + id
    else:
        new_id = id

    if "postfix" in config:
        new_id = new_id + config["postfix"]
    return new_id

import re

#function to patch links
def patch_links(link:str, config: dict) -> str:
    new_link: str = ''
    if len(link) > 0:
        #link_split = link.split(sep=',')
        link_split = re.split(r"[,;]", link)
        links_main_patched: list = []
        for i in range(len(link_split)):
            link_split[i] = link_split[i].strip()
            link_main_part = link_split[i].split(sep='.', maxsplit=1)
            link_main = link_main_part[0]
            link_main_patched = patch_id(link_main, config)
            if len(link_main_part) == 1:
                links_main_patched.append(link_main_patched)
            else:
                link_main_patched_merged = link_main_patched + '.'+ link_main_part[1]
                links_main_patched.append(link_main_patched_merged)

        result = ', '.join(links_main_patched)
        return result

    else:
        return link

# function to change needs, before we generate a need
from sphinx_needs.config import NeedsSphinxConfig
import aspectlib

@aspectlib.Aspect
def changeid(*args, **kwargs):
    print('changeid')
    print('before hook:')
    print("Positional arguments:", args)
    print("Keyword arguments:", kwargs)
    id = kwargs['id']
    print('id: ' + str(id))
    need_type = kwargs['need_type']
    print('need_type: ' + str(need_type))
    app = args[0]
    print('app: ' + str(app))
    state = args[1]
    print('state: ' + str(state))
    docname = ''
    if len(args) >= 3:
        docname = args[2]
    elif 'docname' in kwargs:
        docname = kwargs['docname']
    else:
        docname = state.document.settings.env.docname
    print('docname: ' + str(docname))

    needs_config = NeedsSphinxConfig(app.config)
    needs_types = needs_config.types
    type_prefixes = [t['prefix'] for t in needs_types]

    found: bool = False
    for config in needs_id_prefixes:
        if 'type_prefixes' not in config:
            # add type_prefixes to config
            config['type_prefixes'] = type_prefixes

        for path in config["paths"]:
            if docname.startswith(path):
                found = True
                new_id = patch_id(id, config)
                print('patched id: ' + str(new_id))
                kwargs['id'] = new_id
                for link in config["links"]:
                    if link in kwargs and len(kwargs[link]) > 0:
                        linkcontent = kwargs[link]
                        patched_linkcontent = patch_links(linkcontent, config)
                        print('patched link: ' + str(link) + ' from: ' + str(linkcontent) +' to:' + str(patched_linkcontent))
                        kwargs[link] = patched_linkcontent
            if found:
                break
        if found:
            break

    print('call original function:')
    result = yield aspectlib.Proceed(*args, **kwargs)
    print('after hook:')
    yield aspectlib.Return(result)

#import function to be extended
import sphinx_needs.api

sphinx_needs.api.add_need = changeid(sphinx_needs.api.add_need)

from docutils import nodes
from sphinx_needs.data import SphinxNeedsData

@aspectlib.Aspect
def changeid_for_process_need_ref(*args, **kwargs):
    print('changeid_for_process_need_ref')
    print('before hook:')
    print("Positional arguments:", args)
    print("Keyword arguments:", kwargs)

    app = None
    env = None
    docname:str = ''
    found_nodes = []
    needs_config = None
    type_prefixes = None
    all_needs = None

    if len(args) >= 4:
        print('process ids:')

        app = args[0]
        print('app: ' + str(app))
        env = app.env

        docname = args[2]
        found_nodes = args[3]

        print('docname: ' + str(docname))

        needs_config = NeedsSphinxConfig(app.config)
        needs_types = needs_config.types
        type_prefixes = [t['prefix'] for t in needs_types]

        all_needs = SphinxNeedsData(env).get_needs_view()

    if len(found_nodes) > 0 and len(docname) > 0:

        found: bool = False
        for config in needs_id_prefixes:
            if 'type_prefixes' not in config:
                # add type_prefixes to config
                config['type_prefixes'] = type_prefixes

            for path in config["paths"]:
                if docname.startswith(path):
                    found = True
                    for node_need_ref in found_nodes:
                        print("node_need_ref: " + str(node_need_ref))
                        need_id_full = node_need_ref["reftarget"]

                        need_id_full_patched = patch_links(need_id_full, config)
                        if need_id_full_patched in all_needs:
                            node_need_ref["reftarget"] = need_id_full_patched
                            print('patched needref from: ' + str(need_id_full) +' to:' + str(need_id_full_patched))

                            ref_name: None | str | nodes.Text = node_need_ref.children[0].children[0]
                            if str(need_id_full) == str(ref_name):
                                node_need_ref.children[0].children[0] = nodes.Text(need_id_full_patched)  # type: ignore[index]
                if found:
                    break
            if found:
                break

    print('call original function:')
    result = yield aspectlib.Proceed(*args, **kwargs)
    print('after hook:')
    yield aspectlib.Return(result)

#import function process_need_ref to extend
import sphinx_needs.roles.need_ref

sphinx_needs.roles.need_ref.process_need_ref = changeid_for_process_need_ref(sphinx_needs.roles.need_ref.process_need_ref)

import sphinx_needs.needs
from sphinx_needs.roles.need_ref import NeedRef
sphinx_needs.needs.NODE_TYPES[NeedRef] = changeid_for_process_need_ref(sphinx_needs.roles.need_ref.process_need_ref)

Filter:

You can easily filter for the current file with https://sphinx-needs.readthedocs.io/en/latest/filter.html#filtering-for-needs-on-the-current-page

It is even possible to use the new introduced filter:

.. needtable:: Table of elements within this prefix area
   :show_filters:
   :filter: c.this_prefix()

The this_prefix does support elements which are not part of any prefix.

Fixing Document Headline:

Example:

How-to fix headlines in a toctree

################
Components Level
################

.. toctree::
   :caption: Contents

   original/index
   Component A <A/index>
   Component B <B/index>
   Component C <C/index>

Todo: test if it working with child headlines, too.

Working Features:

• needs

• needpart

• embedded needs

• links between needs, needparts and embedded needs

• filtering with needtable

• filtering with needlist

• filtering with needflow

• use needimport

• use needextend

• use sphinx-test-reports

• need_ref to needs, embedded needs and needpart

Restrictions:

• This methodology is not working with needpie, see https://github.com/useblocks/sphinx-needs/issues/1449.

• This methodology is not working with needbar, see https://github.com/useblocks/sphinx-needs/issues/1449.

• This methodology is not tested with needarch.

• This methodology is not tested with needuml.

• This methodology is not tested with needextract.

• This methodology is not tested with needservice.

• This methodology is not tested with list2need.

• This methodology is not tested with needgantt.

• This methodology is not tested with needsequence.

• We currently do not have an easy way to filter for elements in a dedicated file location