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

[rodrigondec]

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

• folder_1_file_include/system1.dsl the directive is working with !docs "../some_docs_folder"
• folder_1_folder_include/system2.dsl the directive is working with !docs "some_docs_folder"

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:

• declare the container3 and container4 files inside the folder_1_folder_include
• include FILES ONLY from a FOLDER INCLUDE
• include container3.dsl and container4.dsl on system2.dsl

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

[simonbrowndotje]

Thanks for the information - I've opened an issue with a more minimal example at structurizr/dsl#239.