[feature] Do not graph unused library connectors included with --prepend-file

[alecraymond]

I am diagramming a fairly large system (~50 cable assemblies). I've put all of my connectors in a connectors.yml file that I include using the command line --prepend-file option. It would be nice to be able to graph various combinations of connectors in cables/connections.yml files each using a subset of the connectors in connectors.yml. It seems that all connectors are graphed by default. This results in each of my cables/connections.yml files graphing all of the intended cable assemblies, plus all of the unused connectors from connectors.yml.

[kvid]

@alecraymond - Thank you for this suggested feature. It would need to be an optional feature. Othewise, it would be impossible to document single connectors without any connections.

However, you might also consider using the existing inheritance feature. Then you can replace the top connectors: in your common file with e.g. my_project_connectors: and make each connector in the same file a template by appending a unique template name to each connector name entry, e.g. like this: X1: &x1. This way, these connectors are no longer included in the diagram connectors:, but they are YAML templates. In each harness YAML input file, you then include the needed entries by referring to their template names, e.g. like this:

connectors:
  X1: *x1
  X3: *x3
  X4:
    <<: *x3
    notes: This demonstrates reuse of the same template and overriding attributes
cables:
  W1: &w1
    wirecount: 3
    color_code: IEC
  W2: *w1
connections:
  -
    - X1: &3 [1-3]
    - W1: *3
    - X3: *3
    - W2: *3
    - X4: *3

Others use this feature to define their library of often used connectors and wires, but in your use case it can also be used to define all individual connectors in a system/project. If several connectors are similar, you might also reuse the templates in other templates (overriding some attributes when needed). Be aware that all template names must be unique within a global namespace for the complete YAML input to each harness. Connector names have a separate namespace within their section, so you might reuse the same connector name as template name without conflict, but in my example above, I use lower case template names for readability (except my template 3 that demonstrates template usage in a different context).

[kvid]

I'm sorry that I managed to close this issue by a mistake while writing my answer, and my answer was also saved before it was finished. That was not my intention. I have now edited and completed my answer above.

[alecraymond]

@kvid Thanks for the quick and detailed response! I agree that it would need to be an optional feature, preserving the ability to document unused connectors.

Using inheritance as you suggest does result in the diagrams that I expect, and the use of templates reduces maintenance to zero as long as the count/names of templates reused within each child.yml do not need to be changed as the cables and connections are changed. It would be convenient not to be required to add all of the relevant connector template references into each child.yml, but I will do it this way.

[kvid]

@alecraymond - v0.4 was released today, and it includes new functionality that I believe resolves this issue. Please try it and report back here your findings.

[alecraymond]

@kvid Yes, this resolves this issue perfectly. I can include a single connector template file to generate diagrams that display only the cable assemblies with connections. I also like that connectors and cables that are not referenced are displayed as a warning in the output.