structurizr/cli

Allow export of Decisions & Documentation

Closed this issue · 5 comments

toorog commented

Description

As per today, the export command only allows exporting of views. However, the model specified by a DSL File also holds Decisions and Documentation Sections.

My proposal is to allow export of these assets via CLI as well. The possible command might look like this:

  • structurizr-cli export -f docs -w ... -o out_directory/. Export all documentation sections to the directory, using their original filename stored in the filename property in the workspace.json.
  • structurizr-cli export -f decisions -w ... -o out_directory/. Export all decisions, using format json property to determine file extension and id for filename.

Since multiple elements can contain Decisions and / or Doc sections, I propose to make use of the hierarchical identifier to create the subdirectory structure in out_directory.

Priority

I'm willing to add this feature myself and raise a PR (please confirm approach first)

More information

No response

simonbrowndotje commented

Exporting documentation and decisions is much more work than it seems, particularly when you start thinking about how to render embedded diagrams (both views defined within the workspace, and external diagrams from PlantUML, Mermaid, etc) and also things like links between documentation sections and decisions. You might want to take a look at Structurizr Site Generatr that provides some of this functionality already.

toorog commented

I was not talking about any rendering. I was only referring to a 1:1 dump of the files that are embedded in the model (ADRs, Decisions).

simonbrowndotje commented

I'm not sure I see a use case for such a feature ... why can't you just use the original source files that are referenced by the DSL?

toorog commented

I am using a pipeline that produces a workspace.json based on DSL files and ADRs + Documentation. The output of the pipeline is a "documentation release".

There are several other pipelines as well, that solely depend on the released workspace.json as input, and produce various documents / formats as output. e.g.

  • A website (using structurizr-site-generatr)
  • Rendered Views (using structurizr-cli PUML -> SVG, PUML -> PNG, ...)

e.g. I want to now add a pipeline, that uses asciidoctor to render a PDF of the ARC42 documents contained in the model. The pipeline would be:

  1. Download most recent released workspace.json
  2. Dump all files contained in the json <-- This is what is missing in structurizr-cli
  3. Use asciidoctor to generate PDF
simonbrowndotje commented

Closing as not planned ... I'd recommend building your own custom utility to do this instead.