search

structurizr / lite

Structurizr Lite
https://docs.structurizr.com/lite
MIT License
226 stars 26 forks source link

!include directive interferes and 'change' the path for the !docs directive #50

Closed rodrigondec closed 1 year ago

rodrigondec commented 1 year ago

Question

Resume

I got in touch via slack to ask about a error I was receiving whilst trying to use the !docs directive.

Here's the slack channel link https://structurizr.slack.com/archives/C017K4GS0SY/p1680023469824089

I engaged in a disussion/conversation/troubleshoot with @simonbrowndotje and after some exchange I achieved my result to use correctly the !docs directive.

The problem

The !include directive interferes on the path relativity to be used in the !docs directive whilst using some more complex folder architectures and DRY files.

I simplified my case and recreated the behavior on this zip example.zip

workspace.dsl
model.dsl
some_docs_folder/
    1.md
folder_1_file_include/
    folder_2_file_include/
        container1.dsl
    folder_2_folder_include/
        container2.dsl
    system1.dsl
folder_1_folder_include/
    folder_2_file_include/
        container3.dsl
    folder_2_folder_include/
        container4.dsl
    system1.dsl

The goal is to be able to use the directive !docs some_docs_folder on every DSL file on the folder hierarchy.

But on

The cause for the problem

The !include directive works differently for FILE INCLUDE and FOLDER INCLUDE. There's some shenanigans happening with the way the files/paths are processed.

So even if the files are on the same FOLDER HIERARCHICAL level the !docs directive need to be used with different file path relativity!

Another problem encountered

The container3 and container4 DSL's are not possible to be declared using this folder hierarchy and includes.

The reason is that the FOLDER INCLUDE does a recursive include inside the folder. That's a great tool and behavior. But for some cases it's not so great. The way it is, the include folder directive should be used only on LEAF DSL files.

by leaf I mean a DSL file that WILL NOT include another file.

The goal would be:

Proposed actions

  1. investigate folder include path relativity behavior. It's working as expected? If so, this should be documented! If not this should be documented!
  2. create a !include_folder_not_recursively directive to allow this type of modelling/doc architecture!
  3. evidentiate on the documentation that the FOLDER INCLUDE directive is recursive and should be used only to include LEAF DSL files