arc42.tooling

This repository provides a pre-configured template and tooling to help you create comprehensive software documentation based on the arc42 architectural framework. It simplifies the process of generating HTML and PDF documents from your arc42 documentation.

We leverage the following technologies:

• AsciiDoc: A lightweight markup language for writing the arc42 documentation.
• doctoolchain: A powerful toolchain for generating documentation from AsciiDoc, including HTML and PDF formats.
• Structurizr: A tool for creating C4 model diagrams to visualize your system architecture.
• D2: A modern diagram scripting language for creating general diagrams.

Goals

Software needs to be documented well. To lower the entry barrier as much as possible, you get all the tools preconfigured and ready to use so you can just start writing the code.

Non-Goals

Nothing will be generated automatically, you have to update your documentation by hand.

Use Cases

• Generate HTML documentation from arc42 AsciiDoc files.
• Generate PDF documentation from arc42 AsciiDoc files.
• Export arc42 documentation to Confluence.

Get started (Linux, WSL, macOS)

1. Start the Docker Compose environment:

   docker compose up -d
   

   This command will:

   • Serve the generated HTML documentation at http://localhost:8080/arc42/arc42.html.
   • Start the Structurizr Lite server at http://localhost:8081 for creating and viewing C4 model diagrams.
   • Start a local Kroki server, enabling diagram previews within VS Code.

2. Generate Documentation:

   Use the following commands to generate the documentation:

   • HTML: ./dtcw generateHTML
   • PDF: ./dtcw generatePDF

3. Preview Documentation in VS Code:

   Install the AsciiDoc extension in VS Code. This allows you to preview the AsciiDoc files, including embedded diagrams, directly within the editor. The repository includes pre-configured VS Code settings for optimal previewing.

Export to confluence

You can export your arc42 documentation to Confluence using the .forgejo/workflows/confluence.yaml pipeline action.

1. Create a Confluence Personal Access Token (PAT): Follow the instructions at https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html#UsingPersonalAccessTokens-CreatingPATsintheapplication.

2. Add Secrets to Your Repository: Configure the following secrets in your repository settings:

   • ARC42_EXPORT_CONFLUENCE_USER_EMAIL: The email address of the Confluence user.
   • ARC42_EXPORT_CONFLUENCE_USER_PAT: The generated Confluence PAT.

3. Configure docToolchainConfig.groovy: Update the confluence.api and confluence.spaceKey properties in the docToolchainConfig.groovy file. Refer to the doctoolchain documentation for detailed instructions.

Repository structure

├── .forgejo/workflows # Pipeline examples for automated documentation generation and publishing.
├── .vscode # Pre-configured VS Code settings for AsciiDoc preview.
├── output # Generated documentation (HTML and PDF)
└── src # Source files for the documentation.
    ├── arc42 # arc42 AsciiDoc template.
    ├── diagrams # D2 markup files for general diagrams.
    │   └── c4 # Structurizr workspace for C4 model diagrams.
    ├── images # Images used in the documentation.
    └── themes # STACKIT PDF theme

Maintaining and further developing

The Software Architecture channel is responsible for maintaining this repository.

We welcome contributions and suggestions for improvement! Please feel free to create a Pull Request or get in touch with us.