arc42-generator

arc42-generator copied to clipboard

= image:./small-arc42-logo.png[arc42] Generator for Template Formats

If you want to use an arc42 template for your system, you don't need to use this repo - just use one of the templates you find on http://arc42.org/download.

== General Overview

The content (structure + embedded-help) of the arc42 template are maintained in the http://github.com/arc42/arc42-template repository. We call that one the Golden-Master

== How to use this Project

This repository contains a gradle project to convert the golden master into other formats. In order to make it really easy to use this gradle project, the repository includes the gradle-wrapper - a script which will automatically install gradle for you if it is not already installed.

In order to create the other formats from the "Golden Master", follow these steps:

1. open the project with https://gitpod.io image:https://gitpod.io/button/open-in-gitpod.svg[link="https://gitpod.io#https://github.com/arc42/arc42-generator", title="Open in Gitpod", target="_blank"]

This will open gitpod as development environment, clone the project into a docker container and run all needed tasks to generate the various formats. You then only have to check the results and do an add/commit/push

or as a manual alternative you can follow these steps:

0. Downgrade java to Java 8

   sdk install java 8.0.282.j9-adpt

1. Clone this repository:

   git clone [email protected]:arc42/arc42-generator.git

2. Add the "Golden Master" templates by initializing the git submodule and update them

   cd arc42-generator git submodule update -i cd arc42-template git checkout master git pull cd ..

3. Create derived versions from the "Golden Master"

   ./gradlew createTemplatesFromGoldenMaster

This will extract the "plain" and "with-help"-version from the golden master. You'll find the templates in different languages in +build\src_gen+ in AsciiDoc format.

Btw: gradle allows you to "shorten" the command - as long as gradle is still able to guess the command, anything goes :-). ./gradlew createT is as valid as ./gradlew cTFGM.

4. After you have executed the task to create the templates, a new task will become available in gradle:

   ./gradlew arc42

This will generate all other formats, i.e. docx and markdown. The results are created the /build directory.

5. Now you can create the distribution:

   ./gradlew createDistribution

This will create the 'arc42-template/dist' directory with all downloadable versions, nicely compressed.

6. Now you should cross-check, test, verify the generated files :-)

7. Finally you can commit and push these to the arc42-template repository:

   cd arc42-template git commit -m "" *.zip git push https://github.com/arc42/arc42-template.git

=== System Requirements

• Java Runtime (everything above 1.7 should work)
• http://pandoc.org[pandoc] installed with version 1.12.4.2 or higher

As some of the build steps require *locally installed additional tools (like pandoc), you might encounter errors if these are missing on your system.

== General Requirements We collected the +arc42+ link:docs/arc42-requirements.adoc[requirements in a separate document].

== Template Downloads For template downloads please see the https://github.com/arc42/arc42-template[arc42-template] repository or the official download page on http://arc42.org/download.