Replies: 4 comments 7 replies
-
|
Thanks for the great write-up. In my understanding, namespaces are on the textual level already possible, but not used inside Sphinx-Needs. However, parts of this namespace are not automatically created based on the folder or file they are part of. From the technical point I have no concerns using namespace and see the big benefit, but from the usability point of view I have some concerns and open questions: How does linking work?What ID needs to be given to create a valid link?
Which information to take into account to create the namespace elements?I can think of the following sphinx-related elements:
Restructuring the docsWhat happens if:
Expected new features?And most importantly, why spend this extra work? What is the benefit for the user?
If we can answer these questions and keep the usability as good as it is, I would be very happy to support namespaces in one of the next releases. |
Beta Was this translation helpful? Give feedback.
-
|
@danwos Thanks a lot for your quick and detailed reply. Probably, we could separate namespace and usability requirements for namespace. Most parts you mention, I feel, are related to automatic creation of namespace taking into account other information. From my point of view, this could be addressed in the next step. I see currently these possibilities of having a namespace concept in Sphinx-Needs. We could potentially derive some requirements for Sphinx-Needs based on these. Alternative 1: Using detailed identifierThis is a simple solution that can be implemented using the existing Sphinx-Needs features. In this solution, a nomenclature for the identifier shall be defined which makes the need unique The nomenclature shall be used in the definition of IDs and while referencing it. The nomenclature shall ensure that the need is unique in any context. An additional build or a Example .. req-sw:: Need 001
:id: COMPANY1_PROJECT1_COMP1_REQ_SW_001This need can be referred within the project or any other project as: :need:`COMPANY1_PROJECT1_COMP1_REQ_SW_001`Pros
Cons
Alternative 2: Using namespace and identifierThis solution makes use of existing Sphinx-Needs features, but needs additional configuration and minor tool enhancements. In this solution, a simple nomenclature for the identifier shall be defined and an additional namespace for the project. For example, Namespace: Identifier: This enables definition of a needs identifier, without having to repeat a potentially long and redundant namespace The need shall be referred only using the identifier within the project and using namespace and identifier from outside the project. The namespace shall ensure that the need is unique in any context. When needs are exported to external tools from Sphinx-Needs, each need shall by default have only the identifier. An additional build or a ExampleAnd example for the above solution shall be as follows: .. req-sw:: need 001
:id: COMP1_REQ_SW_001This need can be referred within the project as: :need:`COMP1_REQ_SW_001`and from another project as: :need:`COMPANY1_PROJECT1_COMP1_REQ_SW_001`where Pros
Cons
|
Beta Was this translation helpful? Give feedback.
-
|
How about this:
Just my quick 2 cents. |
Beta Was this translation helpful? Give feedback.
-
|
I'm still struggling with the benefit of a namespace. I see 2 scenarios here: a) Outside a sphinx project as a global, company/team-wide unique identifier We can do a, b, or both. However, a possible implementation and the need for certain directives and automatisms are different. a) Global identifiers outside the project.Here it would be enough to have a project-specific identifier, which is used as "prefix" for the needs. Namespace+ID is just an additional attribute for the need object. Gets exported, but is not used internally. b) Inside a sphinx project.Helper directives like We need to define the use case, where exactly we want to use namespaces, and what they are good for. |
Beta Was this translation helpful? Give feedback.
-
|
@danwos The usecase is (a) and (b) above but not separate as you mentioned but together. The usecases I see are:
|
Beta Was this translation helpful? Give feedback.
-
|
These are all requirements for the global identifier use case only ("a" from my previous comment). Let me try to specify the implementation: Technical concept (First draft)Sphinx-Needs object shall get a new attribute: The globally unique project identifier is defined inside Global Need ID Examples:
New/Updated FeaturesThere shall be a new option Example: needs_projects: {
"my_project": {
'base_url': 'http://mydocs/my_project',
'json_url': 'http://mydocs/my_project/needs.json',
'version': '1.0',
'id_prefix': 'ext_',
'css_class': 'external_link',
},
"PRJ_BOND_007": {
'base_url': 'http://007-docs/',
'json_url': 'http://007-docs/needs.json',
'version': '1.0',
'id_prefix': 'ext_',
'css_class': 'external_link',
},
}This can be used in existing directives/roles to reference Sphinx-Needs objects from outside the project. .. needimport::
:project: my_project
:need:`PRJ_BOND_007.34511.3`This all leads to some rules/conclusions:
Just my 2 centsI don't see a big advantage in the above concept, as it just introduces some kind of a unique project_id, which is not necessarily related to Sphinx-Needs objects and could be used for other Sphinx elements as well. It could be also handled outside Sphinx-Needs, by just writing a small script, which updates all IDs in a But maybe I missed something, and for sure it can be a starting point for full namespace support, including namespace parts based on folders, headlines, or whatever. Plus the internal support for using upper namespace-levels in filters and co, like |
Beta Was this translation helpful? Give feedback.
-
@danwos I guess you are right that the namespace definition is something that can be reused, for example, also for intersphinx. In the end, we need a proper concept if we need to replace requirements management tools like DOORS with Sphinx-Needs. In such database based tools, IDs are generated centrally and managed (often with a human-readable ID and a GUID with a mapping between them). For docs-as-code, we need to achieve the same with a single human-readable ID across several sphinx projects (when a multi-repo/project approach is followed). A unique ID is highly important for process conformance for unique referencing of requirements, requirements history tracking, requirements exchange and so on. I will go ahead with a needs.json migrator and |
Beta Was this translation helpful? Give feedback.
-
|
I dont know if it is generally a good idea to couple the namespace into the needs.id as mandatory. In directives (eg.) needextend: For the :need: role however there could be a syntax like :need: Validation however should always use namespace+id for uniqueness. |
Beta Was this translation helpful? Give feedback.
-
|
I agree, if the namespaced ID is important only outside of a project, in this case, it can be an additional attribute and does not affect the current implementation. |
Beta Was this translation helpful? Give feedback.
-
|
It would require to enhance the checking for uniqueness to consider the namespace (namespace+id together is the fully qualified need ID) so you don't need to trust the imported needs serializations. Example: Example fully qualified need ID: |
Beta Was this translation helpful? Give feedback.
-
|
Rather than implementing another proprietary namespace concept from scratch, how about employing a proven and widely used standard, such as Uniform Resource Names (URNs)? This is supported across varying tools and programming languages. For python, there is rdflib which supports URNs as follows: from rdflib import Namespace
COMP1 = Namespace("urn:COMPANY1:PROJECT1:COMP1:")
requirement = COMP1.REQ_SW_001Example fully qualified need ID prefixed: Pros
Cons
|
Beta Was this translation helpful? Give feedback.
-
I'm exploring a way to introduce a namespace concept for IDs within Sphinx-Needs.
Why do we need a namespace in Sphinx-Needs?
This aims to align with common software development practices that allows the creation and maintenance of human-readable IDs to uniquely identify elements.
Unlike database-centric systems, docs-as-code relies on human-readable IDs instead of GUIDs. However, longer human-readable IDs can be challenging to maintain, necessitating the division of IDs into namespaces and individual identifiers.
EDIT:
See detailed usecases here.
Drawing Parallels with Programming Languages
Component A
Component B
In the above example
Component Adefines a namespace and owns it.Component Butilizes this namespace to referenceComponent ACurrent state in Sphinx-Needs
Sphinx-Needs currently offers partial support for namespaces when using needs_external_needs. By employing the
id_prefixconfiguration, it's possible to add a "namespace" to all imported IDs. Consequently, other needs can refer to IDs using this designated namespace, mirroring the software example provided earlier.Open Issues
Several issues need resolution for complete namespace support within Sphinx-Needs:
Namespace support is limited to
needs_external_needsNamespace support remains confined to
needs_external_needs. Consequently, the possibility to create a prefix (namespace) is solely available when using this feature. For instance, during aneeds.jsonexport, there's no mechanism to prefix a namespace. In the end, external tools consuming these IDs might encounter conflicts or need to implement similar mechanisms toneeds_external_needsto append a namespace to each ID.Ownership of namespace in
needs_external_needsUnlike the conventional concept where namespaces are defined and owned by the source (e.g., "ComponentA" defining and owning the namespace used by "ComponentB"), in
needs_external_needs, the namespace is defined and owned by the importer (e.g., "ComponentB"). This results in the need for each component to redefine the namespace independently, deviating from the conventional "namespace" concept and resembling the Python "import - as" keyword alias concept. (Thanks @StephanKuempel for this hint.)A potential workaround involves centrally defining a namespace variable in
conf.pyfor "ComponentA" and utilizing it in the id_prefix of "ComponentB." However, this approach isn't entirely elegant when viewed from a namespace rather than an alias perspective.Namespace usage within the same project not possible
needs_external_needsfacilitates referencing elements via a namespace from an external project but restricts such referencing within the confines of the same project. This implies that while a namespace can be employed to reference "ComponentA" from "ComponentB," it cannot be used reciprocally within "ComponentA" itself.There exist scenarios where employing namespaces consistently to refer to elements, regardless of their origin within or outside the project, makes sense.
Namespace support at project level only
Contrary to languages like C++ or Python that support namespaces at various levels (e.g., C++ at class level, Python at module level), using
needs_external_needs, Sphinx-Needs only allows namespace emulation at the project level. This limitation might prompt the creation of multiple documentation projects solely to leverage the namespace feature.@StephanKuempel @mb-emag @r-o-b-e-r-t-o fyi
Beta Was this translation helpful? Give feedback.
All reactions