82 lines
4.3 KiB
Markdown
82 lines
4.3 KiB
Markdown
# arc42.tooling
|
|
|
|
This repository provides a pre-configured template and tooling to help you create comprehensive software documentation based on the [arc42](https://www.arc42.de/overview/) architectural framework. It simplifies the process of generating HTML and PDF documents from your arc42 documentation.
|
|
|
|
We leverage the following technologies:
|
|
|
|
- **[AsciiDoc](https://asciidoc.org/)**: A lightweight markup language for writing the arc42 documentation.
|
|
- **[doctoolchain](https://doctoolchain.org/)**: A powerful toolchain for generating documentation from AsciiDoc, including HTML and PDF formats.
|
|
- **[Structurizr](https://structurizr.com/)**: A tool for creating [C4 model](https://c4model.com/) diagrams to visualize your system architecture.
|
|
- **[D2](https://d2lang.com/tour/intro/)**: 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:**
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
This command will:
|
|
|
|
- Serve the generated HTML documentation at http://localhost:8080/arc42/arc42.html.
|
|
- Start the [Structurizr Lite](https://docs.structurizr.com/lite) server at http://localhost:8081 for creating and viewing C4 model diagrams.
|
|
- Start a local [Kroki](https://kroki.io/) 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](https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode) 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](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](https://doctoolchain.org/docToolchain/v2.0.x/020_tutorial/070_publishToConfluence.html#_publish_your_docs_to_confluence) for detailed instructions.
|
|
|
|
## Repository structure
|
|
|
|
```bash
|
|
├── .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](https://indecagmbh.sharepoint.com/sites/Intranet/SitePages/Channels---Software-Architecture.aspx?web=1) 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.
|