Homebase-Software-Architecture/arc42.tooling
6
1
Fork 0
Code Issues 1 Pull requests Projects 1 Releases Packages Wiki Activity Actions

updated readme and removed old mmmake theme

Browse source
This commit is contained in:
Stephan Weißenberger 2024-10-04 17:36:07 +02:00
parent b0faed564c
commit a6984fafd0
5 changed files with 60 additions and 3620 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

61
README.md
View file

@ -1,3 +1,62 @@
# arc42.tooling
Contains everything needed to create a arc42 documentation for your project as a template with tooling to create html and pdf documents.
Contains everything needed to create a [arc42](https://www.arc42.de/overview/) documentation for your project as a template with tooling to create html and pdf documents.
We are using [asciidoc](https://asciidoc.org/) as a markup language and [d2](https://d2lang.com/tour/intro/) to draw diagrams.
We use [asciidoctor docker image](https://github.com/asciidoctor/docker-asciidoctor) 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`
or
`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](https://indecagmbh.sharepoint.com/sites/Intranet/SitePages/Channels---Software-Architecture.aspx?web=1) 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.

451
docToolchainConfig.groovy
View file

@ -1,451 +0,0 @@
outputPath = 'build'
// Path where the docToolchain will search for the input files.
// This path is appended to the docDir property specified in gradle.properties
// or in the command line, and therefore must be relative to it.
inputPath = './src/';
// the pdfThemeDir config in this file is outdated.
// please check http://doctoolchain.org/docToolchain/v2.0.x/020_tutorial/030_generateHTML.html#_pdf_style for further details
// pdfThemeDir = './src/docs/pdfTheme'
inputFiles = [
[file: 'arc42/arc42.adoc', formats: ['html','pdf']],
/** inputFiles **/
]
//folders in which asciidoc will find images.
//these will be copied as resources to ./images
//folders are relative to inputPath
imageDirs = [
'images/.',
/** imageDirs **/
]
// these are directories (dirs) and files which Gradle monitors for a change
// in order to decide if the docs have to be re-build
taskInputsDirs = [
"${inputPath}",
// "${inputPath}/src",
// "${inputPath}/images",
]
taskInputsFiles = []
//*****************************************************************************************
// Configuration for customTasks
// create a new Task with ./dtcw createTask
customTasks = [
/** customTasks **/
]
//*****************************************************************************************
//Configuration for microsite: generateSite + previewSite
microsite = [:]
// these properties will be set as jBake properties
// microsite.foo will be site.foo in jBake and can be used as config.site_foo in a template
// see https://jbake.org/docs/2.6.4/#configuration for how to configure jBake
// other properties listed here might be used in the jBake templates and thus are not
// documented in the jBake docs but hopefully in the template docs.
microsite.with {
/** start:microsite **/
// is your microsite deployed with a context path?
contextPath = '/'
// configure a port on which your preview server will run
previewPort = 8042
// the folder of a site definition (theme) relative to the docDir+inputPath
//siteFolder = '../site'
/** end:microsite **/
//project theme
//site folder relative to the docs folder
//see 'copyTheme' for more details
siteFolder = '../site'
// the title of the microsite, displayed in the upper left corner
title = '##site-title##'
// the next items configure some links in the footer
//
// contact eMail
// example: mailto:bert@example.com
footerMail = '##footer-email##'
//
// twitter account url
footerTwitter = '##twitter-url##'
//
// Stackoverflow QA
footerSO = '##Stackoverflow-url##'
//
// Github Repository
footerGithub = '##Github-url##'
//
// Slack Channel
footerSlack = '##Slack-url##'
//
// Footer Text
// example: <small class="text-white">built with docToolchain and jBake <br /> theme: docsy</small>
footerText = '<small class="text-white">built with <a href="https://doctoolchain.org">docToolchain</a> and <a href="https://jbake.org">jBake</a> <br /> theme: <a href="https://www.docsy.dev/">docsy</a></small>'
//
// site title if no other title is given
title = 'docToolchain'
//
// the url to create an issue in github
// Example: https://github.com/docToolchain/docToolchain/issues/new
issueUrl = '##issue-url##'
//
// the base url for code files in github
// Example: https://github.com/doctoolchain/doctoolchain/edit/master/src/docs
branch = System.getenv("DTC_PROJECT_BRANCH")?:'-'
gitRepoUrl = '##git-repo-url##'
//
// the location of the landing page
landingPage = 'landingpage.gsp'
// the menu of the microsite. A map of [code:'title'] entries to specify the order and title of the entries.
// the codes are autogenerated from the folder names or :jbake-menu: attribute entries from the .adoc file headers
// set a title to '-' in order to remove this menu entry.
menu = [:]
/**
tag::additionalConverters[]
if you need support for additional markup converters, you can configure them here
you have three different types of script you can define:
- groovy: just groovy code as string
- groovyFile: path to a groovy script
- bash: a bash command. It will receive the name of the file to be converted as first argument
`groovy` and `groovyFile` will have access to the file and config object
`dtcw:rstToHtml.py` is an internal script to convert restructuredText.
Needs `python3` and `docutils` installed.
end::additionalConverters[]
**/
additionalConverters = [
//'.one': [command: 'println "test"+file.canonicalPath', type: 'groovy'],
//'.two': [command: 'scripts/convert-md.groovy', type: 'groovyFile'],
//'.rst': [command: 'dtcw:rstToHtml.py', type: 'bash'],
]
// if you prefere another convention regarding the automatic generation
// of jBake headers, you can configure a script to modify them here
// the script has access to
// - file: the current object
// - config: the config object (this file, but parsed)
// - headers: already parsed headers to be modified
/**
customConvention = """
System.out.println file.canonicalPath
headers.title += " - from CustomConvention"
""".stripIndent()
**/
}
//*****************************************************************************************
//Configuration for exportChangelog
exportChangelog = [:]
changelog.with {
// Directory of which the exportChangelog task will export the changelog.
// It should be relative to the docDir directory provided in the
// gradle.properties file.
dir = 'src/docs'
// Command used to fetch the list of changes.
// It should be a single command taking a directory as a parameter.
// You cannot use multiple commands with pipe between.
// This command will be executed in the directory specified by changelogDir
// it the environment inherited from the parent process.
// This command should produce asciidoc text directly. The exportChangelog
// task does not do any post-processing
// of the output of that command.
//
// See also https://git-scm.com/docs/pretty-formats
cmd = 'git log --pretty=format:%x7c%x20%ad%x20%n%x7c%x20%an%x20%n%x7c%x20%s%x20%n --date=short'
}
//*****************************************************************************************
//tag::confluenceConfig[]
//Configuration for publishToConfluence
confluence = [:]
/**
//tag::input-config[]
*input*
is an array of files to upload to Confluence with the ability
to configure a different parent page for each file.
=== Attributes
- `file`: absolute or relative path to the asciidoc generated html file to be exported
- `url`: absolute URL to an asciidoc generated html file to be exported
- `ancestorName` (optional): the name of the parent page in Confluence as string;
this attribute has priority over ancestorId, but if page with given name doesn't exist,
ancestorId will be used as a fallback
- `ancestorId` (optional): the id of the parent page in Confluence as string; leave this empty
if a new parent shall be created in the space
- `preambleTitle` (optional): the title of the page containing the preamble (everything
before the first second level heading). Default is 'arc42'
The following four keys can also be used in the global section below
- `spaceKey` (optional): page specific variable for the key of the confluence space to write to
- 'allInOnePage' (optional): page specific variable to determine whether documentation is written to just one
Confluence page or separate ones per chapter (default)
- `createSubpages` (optional): page specific variable to determine whether ".sect2" sections shall be split from the current page into subpages
- `pagePrefix` (optional): page specific variable, the pagePrefix will be a prefix for the page title and it's sub-pages
use this if you only have access to one confluence space but need to store several
pages with the same title - a different pagePrefix will make them unique
- `pageSuffix` (optional): same usage as prefix but appended to the title and it's subpages
only 'file' or 'url' is allowed. If both are given, 'url' is ignored
//end::input-config[]
**/
confluence.with {
input = [
[ file: "build/html5/arc42/arc42.html" ],
]
//ancestorName = '4.+arc42'
// endpoint of the confluenceAPI (REST) to be used
// verfiy that you got the correct endpoint by browsing to
// e.g. https://mmmake.atlassian.net/wiki/rest/api/user/current
// you should get a valid json which describes your current user
// a working example is https://arc42-template.atlassian.net/wiki/rest/api/user/current
api = System.getenv("ARC42_EXPORT_CONFLUENCE_API")
// Additionally, spaceKey, createSubpages, pagePrefix and pageSuffix can be globally defined here. The assignment in the input array has precedence
// the key of the confluence space to write to
spaceKey = System.getenv("ARC42_EXPORT_CONFLUENCE_SPACE_KEY")
// variable to determine whether the whole document should be uploaded as just one page or split into separate
// pages per chapter
subpagesForSections = 1
// variable to determine whether ".sect2" sections shall be split from the current page into subpages
//createSubpages = true
// the pagePrefix will be a prefix for each page title
// use this if you only have access to one confluence space but need to store several
// pages with the same title - a different pagePrefix will make them unique
pagePrefix = ''
pageSuffix = ' (read-only)'
/*
WARNING: It is strongly recommended to store credentials securely instead of commiting plain text values to your git repository!!!
Tool expects credentials that belong to an account which has the right permissions to to create and edit confluence pages in the given space.
Credentials can be used in a form of:
- passed parameters when calling script (-PconfluenceUser=myUsername -PconfluencePass=myPassword) which can be fetched as a secrets on CI/CD or
- gradle variables set through gradle properties (uses the 'confluenceUser' and 'confluencePass' keys)
Often, same credentials are used for Jira & Confluence, in which case it is recommended to pass CLI parameters for both entities as
-Pusername=myUser -Ppassword=myPassword
*/
//optional API-token to be added in case the credentials are needed for user and password exchange.
//apikey = "[API-token]"
// HTML Content that will be included with every page published
// directly after the TOC. If left empty no additional content will be
// added
// extraPageContent = '<ac:structured-macro ac:name="warning"><ac:parameter ac:name="title" /><ac:rich-text-body>This is a generated page, do not edit!</ac:rich-text-body></ac:structured-macro>
extraPageContent = ''
// enable or disable attachment uploads for local file references
enableAttachments = false
// default attachmentPrefix = attachment - All files to attach will require to be linked inside the document.
// attachmentPrefix = "attachment"
// Optional proxy configuration, only used to access Confluence
// schema supports http and https
// proxy = [host: 'my.proxy.com', port: 1234, schema: 'http']
// Optional: specify which Confluence OpenAPI Macro should be used to render OpenAPI definitions
// possible values: ["confluence-open-api", "open-api", true]. true is the same as "confluence-open-api" for backward compatibility
// useOpenapiMacro = "confluence-open-api"
}
//end::confluenceConfig[]
//*****************************************************************************************
//tag::exportEAConfig[]
//Configuration for the export script 'exportEA.vbs'.
// The following parameters can be used to change the default behaviour of 'exportEA'.
// All parameter are optionally.
// Parameter 'connection' allows to select a certain database connection by using the ConnectionString as used for
// directly connecting to the project database instead of looking for EAP/EAPX files inside and below the 'src' folder.
// Parameter 'packageFilter' is an array of package GUID's to be used for export. All images inside and in all packages below the package represented by its GUID are exported.
// A packageGUID, that is not found in the currently opened project, is silently skipped.
// PackageGUID of multiple project files can be mixed in case multiple projects have to be opened.
exportEA.with {
// OPTIONAL: Set the connection to a certain project or comment it out to use all project files inside the src folder or its child folder.
// connection = "DBType=1;Connect=Provider=SQLOLEDB.1;Integrated Security=SSPI;Persist Security Info=False;Initial Catalog=[THE_DB_NAME_OF_THE_PROJECT];Data Source=[server_hosting_database.com];LazyLoad=1;"
// OPTIONAL: Add one or multiple packageGUIDs to be used for export. All packages are analysed, if no packageFilter is set.
// packageFilter = [
// "{A237ECDE-5419-4d47-AECC-B836999E7AE0}",
// "{B73FA2FB-267D-4bcd-3D37-5014AD8806D6}"
// ]
// OPTIONAL: relative path to base 'docDir' to which the diagrams and notes are to be exported
// exportPath = "src/docs/"
// OPTIONAL: relative path to base 'docDir', in which Enterprise Architect project files are searched
// searchPath = "src/docs/"
}
//end::exportEAConfig[]
//tag::htmlSanityCheckConfig[]
htmlSanityCheck.with {
//sourceDir = "build/html5/site"
//checkingResultsDir =
}
//end::htmlSanityCheckConfig[]
//tag::jiraConfig[]
// Configuration for Jira related tasks
jira = [:]
jira.with {
// endpoint of the JiraAPI (REST) to be used
api = 'https://your-jira-instance'
/*
WARNING: It is strongly recommended to store credentials securely instead of commiting plain text values to your git repository!!!
Tool expects credentials that belong to an account which has the right permissions to read the JIRA issues for a given project.
Credentials can be used in a form of:
- passed parameters when calling script (-PjiraUser=myUsername -PjiraPass=myPassword) which can be fetched as a secrets on CI/CD or
- gradle variables set through gradle properties (uses the 'jiraUser' and 'jiraPass' keys)
Often, Jira & Confluence credentials are the same, in which case it is recommended to pass CLI parameters for both entities as
-Pusername=myUser -Ppassword=myPassword
*/
// the key of the Jira project
project = 'LRP1'
// the format of the received date time values to parse
dateTimeFormatParse = "yyyy-MM-dd'T'H:m:s.SSSz" // i.e. 2020-07-24'T'9:12:40.999 CEST
// the format in which the date time should be saved to output
dateTimeFormatOutput = "dd.MM.yyyy HH:mm:ss z" // i.e. 24.07.2020 09:02:40 CEST
// the label to restrict search to
label =
// Legacy settings for Jira query. This setting is deprecated & support for it will soon be completely removed. Please use JiraRequests settings
//jql = "project='%jiraProject%' AND labels='%jiraLabel%' ORDER BY priority DESC, duedate ASC"
// Base filename in which Jira query results should be stored
resultsFilename = 'JiraTicketsContent'
saveAsciidoc = true // if true, asciidoc file will be created with *.adoc extension
saveExcel = true // if true, Excel file will be created with *.xlsx extension
// Output folder for this task inside main outputPath
resultsFolder = 'JiraRequests'
/*
List of requests to Jira API:
These are basically JQL expressions bundled with a filename in which results will be saved.
User can configure custom fields IDs and name those for column header,
i.e. customfield_10026:'Story Points' for Jira instance that has custom field with that name and will be saved in a coloumn named "Story Points"
*/
requests = [
new JiraRequest(
filename:"File1_Done_issues",
jql:"project='%jiraProject%' AND status='Done' ORDER BY duedate ASC",
customfields: [customfield_10026:'Story Points']
),
new JiraRequest(
filename:'CurrentSprint',
jql:"project='%jiraProject%' AND Sprint in openSprints() ORDER BY priority DESC, duedate ASC",
customfields: [customfield_10026:'Story Points']
),
]
}
@groovy.transform.Immutable
class JiraRequest {
String filename //filename (without extension) of the file in which JQL results will be saved. Extension will be determined automatically for Asciidoc or Excel file
String jql // Jira Query Language syntax
Map<String,String> customfields // map of customFieldId:displayName values for Jira fields which don't have default names, i.e. customfield_10026:StoryPoints
}
//end::jiraConfig[]
//tag::openApiConfig[]
// Configuration for OpenAPI related task
openApi = [:]
// 'specFile' is the name of OpenAPI specification yaml file. Tool expects this file inside working dir (as a filename or relative path with filename)
// 'infoUrl' and 'infoEmail' are specification metadata about further info related to the API. By default this values would be filled by openapi-generator plugin placeholders
//
openApi.with {
specFile = 'src/docs/petstore-v2.0.yaml' // i.e. 'petstore.yaml', 'src/doc/petstore.yaml'
infoUrl = 'https://my-api.company.com'
infoEmail = 'info@company.com'
}
//end::openApiConfig[]
//tag::sprintChangelogConfig[]
// Sprint changelog configuration generate changelog lists based on tickets in sprints of an Jira instance.
// This feature requires at least Jira API & credentials to be properly set in Jira section of this configuration
sprintChangelog = [:]
sprintChangelog.with {
sprintState = 'closed' // it is possible to define multiple states, i.e. 'closed, active, future'
ticketStatus = "Done, Closed" // it is possible to define multiple ticket statuses, i.e. "Done, Closed, 'in Progress'"
showAssignee = false
showTicketStatus = false
showTicketType = true
sprintBoardId = 12345 // Jira instance probably have multiple boards; here it can be defined which board should be used
// Output folder for this task inside main outputPath
resultsFolder = 'Sprints'
// if sprintName is not defined or sprint with that name isn't found, release notes will be created on for all sprints that match sprint state configuration
sprintName = 'PRJ Sprint 1' // if sprint with a given sprintName is found, release notes will be created just for that sprint
allSprintsFilename = 'Sprints_Changelogs' // Extension will be automatically added.
}
//end::sprintChangelogConfig[]
//tag::collectIncludesConfig[]
collectIncludes = [:]
collectIncludes.with {
fileFilter = "adoc" // define which files are considered. default: "ad|adoc|asciidoc"
minPrefixLength = "3" // define what minimum length the prefix. default: "3"
maxPrefixLength = "3" // define what maximum length the prefix. default: ""
separatorChar = "_" // define the allowed separators after prefix. default: "-_"
cleanOutputFolder = true // should the output folder be emptied before generation? defailt: false
}
//end::collectIncludesConfig[]

64
readme 2.md
View file

@ -1,64 +0,0 @@
# mmmake Software Architecture Channel Tooling Repository
Welcome! As we like to write code we want also want to write our documentation with code.
Within this repository we will give you everything required to create an architecture description
based on the widly known architecture template [ARC42](https://www.arc42.de/overview/).
We will use [asciidoc](https://asciidoc.org/) as a markup language and [d2](https://d2lang.com/tour/intro/) to draw diagrams.
We will use [asciidoctor docker image](https://github.com/asciidoctor/docker-asciidoctor) to generate the required artifacts out of asciidoc.
## What we want to achieve with this / Why this exists
We want our software to be documented well. To make this as easy as possbile for everyone we want
to give you all the tools preconfigured and ready to use so you can just start writing the code.
## Capabilities
- Create html from arc42 asciidoc (the images are included in html, not linked)
- Create pdf from arc42 asciidoc
- Create d2 diagrams as svg to be used by arc42 generation
- 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`
or
`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](https://indecagmbh.sharepoint.com/sites/Intranet/SitePages/Channels---Software-Architecture.aspx?web=1) 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.

3042
src/images/mmmake_logo_landscape_claim_black.svg
View file

File diff suppressed because it is too large Load diff
Side by side

Before

Width:  |  Height:  |  Size: 224 KiB

62
src/themes/mmmake-theme.yml
View file

@ -1,62 +0,0 @@
title_page:
align: left
page:
layout: portrait
margin: [0.75in, 1in, 0.75in, 1in]
size: A4
font:
catalog:
# Noto Serif supports Latin, Latin-1 Supplement, Latin Extended-A, Greek, Cyrillic, Vietnamese & an assortment of symbols
Arial:
normal: Arial.ttf
bold: Arial_Bold.ttf
italic: Arial_Italic.ttf
bold_italic: Arial_Bold_Italic.ttf
Courier:
normal: Courier_New.ttf
fallbacks:
- Arial
conum:
font_family: Arial
code:
font_family: Arial
base:
font_family: Arial
font_color: #1E1E1E
line_height_length: 17
line_height: $base_line_height_length / $base_font_size
vertical_rhythm: $base_line_height_length
heading:
font_family: Arial
font_color: #00FF00
font_size: 17
font_style: bold
line_height: 1.2
margin_bottom: $vertical_rhythm
link:
font_color: #FF0096
list:
indent: $base_font_size * 1.5
header:
height: 0.75in
line_height: 1
recto_content:
center: '{document-title}'
verso_content:
center: '{document-title}'
footer:
height: 0.75in
line_height: 1
recto:
right:
content: '{chapter-title} | *{page-number}*'
verso:
left:
content: '*{page-number}* | {chapter-title}'
image:
align: center
caption:
align: center
font_color: #000000
font_size: 10