arc42.tooling

Contains everything needed to create a arc42 documentation for your project as a template with tooling to create html and pdf documents.

We are using asciidoc as a markup language and d2 to draw diagrams. We use asciidoctor docker image to generate the required artifacts out of asciidoc.

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

Create html from arc42 asciidoc
Create pdf from arc42 asciidoc
Create d2 diagrams as svg to be used in the arc42 documentation
Export arc42 to confluence

Get started MacOs/Linux

download required dependencies, only needed on the first time: ./init.sh
create the documentation: ./create-html.sh or ./create-pdf.sh

Export to confluence

Extensive guide here: https://doctoolchain.org/docToolchain/v2.0.x/020_tutorial/070_publishToConfluence.html#_publish_your_docs_to_confluence

Needed env vars ARC42_EXPORT_CONFLUENCE_API e.g. https://mmmake.atlassian.net/wiki/rest/api/ ARC42_EXPORT_CONFLUENCE_SPACE_KEY e.g. ANT

either ARC42_EXPORT_CONFLUENCE_USER_EMAIL and ARC42_EXPORT_CONFLUENCE_USER_PAT

ARC42_EXPORT_CONFLUENCE_USER_BEARER see https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html#UsingPersonalAccessTokens-CreatingPATsintheapplication

Use the export-to-confluence.yml as pipeline in azure devops

It is important that this documentation is located in the /.docs folder inside the root of your repository. It is also recommended to put this alongside your code to make sure the documentation and code can be merged simultaneously.

Repository structure

/azure
- note: contains pipeline examples to automatically generate the documentation and publish it to multiple targets.
/src
- /arc42
  - note: contains the arc42 ascii doc template.
- /diagrams
  - note: contains the d2 markup files.
- /images
  - note: contains the images that are used while generating the documentation. D2 diagrams are automatically converted and copied into the images folder while creating documentation and are deleted afterwards.
/scripts
- note: contains the scripts to create diagrams, generate the documentation and so on.

Maintaining and further developing

The software architecture channel is responsible for this repository.

Challenges and better ideas are always welcome.

Feel free to create a Pull Request or get in touch with us.

2.8 KiB Raw Blame History