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
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
investigate folder include path relativity behavior. It's working as expected? If so, this should be documented! If not this should be documented!
create a !include_folder_not_recursively directive to allow this type of modelling/doc architecture!
evidentiate on the documentation that the FOLDER INCLUDE directive is recursive and should be used only to include LEAF DSL files
Question
Resume
I got in touch via slack to ask about a error I was receiving whilst trying to use the
!docs
directive.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.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.
The goal would be:
folder_1_folder_include
container3.dsl
andcontainer4.dsl
onsystem2.dsl
Proposed actions
!include_folder_not_recursively
directive to allow this type of modelling/doc architecture!