moved all files from old to new repo
This commit is contained in:
Stephan Weißenberger
parent
71bf9d7091
commit
32f854792e
50 changed files with 5654 additions and 0 deletions
28
.devops/export-as-artifact.yml
Normal file
28
.devops/export-as-artifact.yml
Normal file
|
|
@ -0,0 +1,28 @@
|
|||
trigger:
|
||||
branches:
|
||||
include:
|
||||
- "*"
|
||||
paths:
|
||||
include:
|
||||
- .docs/.arc42/src
|
||||
pool:
|
||||
vmImage: ubuntu-latest
|
||||
steps:
|
||||
- script: |
|
||||
chmod +x ./init.sh
|
||||
./init.sh
|
||||
|
||||
chmod +x ./create-pdf.sh
|
||||
./create-pdf.sh
|
||||
workingDirectory: .docs/.arc42/
|
||||
- script: |
|
||||
# Get the full branch reference from Azure DevOps environment variables
|
||||
FULL_BRANCH_REF=$(Build.SourceBranch)
|
||||
|
||||
# Remove the "refs/heads/" prefix to get just the branch name
|
||||
BRANCH_NAME=${FULL_BRANCH_REF#refs/heads/}
|
||||
|
||||
# Publish the PDF file as an artifact with the filename as the name
|
||||
echo "##vso[artifact.upload containerfolder=arc42;artifactname=arc42-$(date +'%Y%m%d%H%M%S')-$BRANCH_NAME;]$(System.DefaultWorkingDirectory)/.docs/.arc42/output/arc42.pdf"
|
||||
displayName: "Publish PDF Artifacts"
|
||||
workingDirectory: .docs/.arc42/
|
||||
19
.devops/export-to-confluence.yml
Normal file
19
.devops/export-to-confluence.yml
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
trigger:
|
||||
branches:
|
||||
include:
|
||||
- main
|
||||
paths:
|
||||
include:
|
||||
- .docs/.arc42/src
|
||||
|
||||
pool:
|
||||
vmImage: ubuntu-latest
|
||||
|
||||
variables:
|
||||
group:
|
||||
|
||||
steps:
|
||||
- script: |
|
||||
chmod +x ./scripts/export-to-confluence.sh
|
||||
./scripts/export-to-confluence.sh
|
||||
workingDirectory: .docs/.arc42/
|
||||
7
.gitignore
vendored
Normal file
7
.gitignore
vendored
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
.gradle
|
||||
dtcw
|
||||
build/
|
||||
.DS_Store
|
||||
output
|
||||
src/diagrams/*.svg
|
||||
.vscode/settings.json
|
||||
10
create-html.sh
Executable file
10
create-html.sh
Executable file
|
|
@ -0,0 +1,10 @@
|
|||
#!/usr/bin/env bash
|
||||
|
||||
./scripts/prepare.sh
|
||||
|
||||
echo "==========================="
|
||||
echo " generating HTML"
|
||||
echo "==========================="
|
||||
docker run -it -v "$(pwd)":"/documents/" asciidoctor/docker-asciidoctor asciidoctor -a data-uri src/arc42/arc42.adoc -o output/arc42.html
|
||||
|
||||
./scripts/cleanup.sh
|
||||
12
create-pdf.sh
Executable file
12
create-pdf.sh
Executable file
|
|
@ -0,0 +1,12 @@
|
|||
#!/usr/bin/env bash
|
||||
chmod +x ./scripts/prepare.sh
|
||||
./scripts/prepare.sh
|
||||
|
||||
echo "==========================="
|
||||
echo " generating PDF"
|
||||
echo "==========================="
|
||||
|
||||
docker run --rm -v "$(pwd):/documents/" asciidoctor/docker-asciidoctor asciidoctor -r asciidoctor-pdf -b pdf -a data-uri src/arc42/arc42.adoc -o output/arc42.pdf
|
||||
|
||||
chmod +x ./scripts/cleanup.sh
|
||||
./scripts/cleanup.sh
|
||||
451
docToolchainConfig.groovy
Normal file
451
docToolchainConfig.groovy
Normal file
|
|
@ -0,0 +1,451 @@
|
|||
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[]
|
||||
7
init.sh
Executable file
7
init.sh
Executable file
|
|
@ -0,0 +1,7 @@
|
|||
#!/usr/bin/env bash
|
||||
|
||||
echo "==========================="
|
||||
echo " get d2"
|
||||
echo "==========================="
|
||||
curl -fsSL https://d2lang.com/install.sh | sh -s --
|
||||
|
||||
64
readme 2.md
Normal file
64
readme 2.md
Normal file
|
|
@ -0,0 +1,64 @@
|
|||
# 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.
|
||||
|
||||
7
scripts/cleanup.sh
Executable file
7
scripts/cleanup.sh
Executable file
|
|
@ -0,0 +1,7 @@
|
|||
#!/usr/bin/env bash
|
||||
|
||||
echo "==========================="
|
||||
echo " cleaning up"
|
||||
echo "==========================="
|
||||
chmod +x ./scripts/delete-created-diagrams.sh
|
||||
./scripts/delete-created-diagrams.sh
|
||||
22
scripts/create-diagrams.sh
Executable file
22
scripts/create-diagrams.sh
Executable file
|
|
@ -0,0 +1,22 @@
|
|||
#!/usr/bin/env bash
|
||||
|
||||
echo "==========================="
|
||||
echo " creating diagrams"
|
||||
echo "==========================="
|
||||
diagrams_target_dir=./src/images
|
||||
diagrams_dir=./src/diagrams
|
||||
|
||||
# Recursively find all d2 files in diagrams directory and its subdirectories
|
||||
diagrams=$(find ${diagrams_dir} -type f -name '*.d2')
|
||||
|
||||
for entry in $diagrams
|
||||
do
|
||||
echo "$entry"
|
||||
# Extract the relative path without the extension
|
||||
relative_path=${entry#"$diagrams_dir/"}
|
||||
filename="${relative_path%.*}"
|
||||
# Generate the target SVG path by combining the target directory and relative path
|
||||
svg_path="${diagrams_target_dir}/${filename}.svg"
|
||||
|
||||
d2 "$entry" "$svg_path"
|
||||
done
|
||||
25
scripts/delete-created-diagrams.sh
Executable file
25
scripts/delete-created-diagrams.sh
Executable file
|
|
@ -0,0 +1,25 @@
|
|||
#!/usr/bin/env bash
|
||||
|
||||
echo "==========================="
|
||||
echo " deleting created diagrams"
|
||||
echo "==========================="
|
||||
diagrams_target_dir=./src/images
|
||||
diagrams_dir=./src/diagrams
|
||||
|
||||
# Recursively find all *.d2 files in the diagrams directory and its subdirectories
|
||||
diagrams=$(find ${diagrams_dir} -type f -name '*.d2')
|
||||
|
||||
for d2file in $diagrams
|
||||
do
|
||||
# Construct the corresponding SVG file path by replacing the .d2 extension with .svg
|
||||
svgfile="${diagrams_target_dir}${d2file#${diagrams_dir}}"
|
||||
svgfile="${svgfile%.d2}.svg"
|
||||
|
||||
# Check if the corresponding SVG file exists and then delete it
|
||||
if [ -e "$svgfile" ]; then
|
||||
echo "Deleting $svgfile"
|
||||
rm "$svgfile"
|
||||
else
|
||||
echo "SVG file not found for $d2file"
|
||||
fi
|
||||
done
|
||||
452
scripts/docToolchainConfig.groovy
Normal file
452
scripts/docToolchainConfig.groovy
Normal file
|
|
@ -0,0 +1,452 @@
|
|||
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" ],
|
||||
]
|
||||
|
||||
// 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")
|
||||
|
||||
// the title of the page containing the preamble (everything the first second level heading). Default is 'arc42'
|
||||
preambleTitle = ''
|
||||
|
||||
// variable to determine whether the whole document should be uploaded as just one page or split into separate
|
||||
// pages per chapter
|
||||
allInOnePage = false
|
||||
|
||||
// variable to determine whether ".sect2" sections shall be split from the current page into subpages
|
||||
createSubpages = false
|
||||
|
||||
// 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[]
|
||||
29
scripts/export-to-confluence.sh
Normal file
29
scripts/export-to-confluence.sh
Normal file
|
|
@ -0,0 +1,29 @@
|
|||
###
|
||||
# PREPARE
|
||||
###
|
||||
chmod +x ./init.sh
|
||||
./init.sh
|
||||
|
||||
chmod +x ./scripts/prepare.sh
|
||||
./scripts/prepare.sh
|
||||
|
||||
curl -Lo dtcw doctoolchain.github.io/dtcw
|
||||
chmod +x ./dtcw
|
||||
|
||||
./dtcw install doctoolchain
|
||||
|
||||
###
|
||||
# EXPORT
|
||||
###
|
||||
|
||||
echo "==========================="
|
||||
echo " start publishToConfluence"
|
||||
echo "==========================="
|
||||
|
||||
./dtcw publishToConfluence -PbearerToken="$ARC42_EXPORT_CONFLUENCE_USER_BEARER" -PconfluenceUser="$ARC42_EXPORT_CONFLUENCE_USER_EMAIL" -PconfluencePass="$ARC42_EXPORT_CONFLUENCE_USER_PAT" --info
|
||||
|
||||
###
|
||||
# CLEAN
|
||||
###
|
||||
chmod +x ./scripts/cleanup.sh
|
||||
./scripts/cleanup.sh
|
||||
7
scripts/prepare.sh
Executable file
7
scripts/prepare.sh
Executable file
|
|
@ -0,0 +1,7 @@
|
|||
#!/usr/bin/env bash
|
||||
|
||||
echo "==========================="
|
||||
echo " preparing"
|
||||
echo "==========================="
|
||||
chmod +x ./scripts/create-diagrams.sh
|
||||
./scripts/create-diagrams.sh
|
||||
2
src/arc42/.asciidoctorconfig.adoc
Normal file
2
src/arc42/.asciidoctorconfig.adoc
Normal file
|
|
@ -0,0 +1,2 @@
|
|||
:imagesdir: ../images
|
||||
|
||||
108
src/arc42/arc42.adoc
Normal file
108
src/arc42/arc42.adoc
Normal file
|
|
@ -0,0 +1,108 @@
|
|||
:imagesdir: ../images
|
||||
:jbake-menu: -
|
||||
:pdf-themesdir: /documents/src/themes/
|
||||
:pdf-fontsdir: /documents/src/themes/fonts
|
||||
:pdf-theme: stackit
|
||||
// header file for arc42-template,
|
||||
// including all help texts
|
||||
//
|
||||
// ====================================
|
||||
|
||||
// configure EN settings for asciidoc
|
||||
include::chapters/config.adoc[]
|
||||
|
||||
= image:STACKIT_Logo_CMYK_Regular_Petrol-MZ.svg[stackit, 350] image:arc42-logo.png[arc42] <PROJECTNAME> ARC42
|
||||
:revnumber: 1.0
|
||||
:revdate: March 2023
|
||||
:revremark: (sw arc channel template)
|
||||
// toc-title definition MUST follow document title without blank line!
|
||||
:toc-title: Table of Contents
|
||||
|
||||
include::chapters/about-arc42.adoc[]
|
||||
|
||||
|
||||
|
||||
image::example.svg["Example usage of d2 diagram"]
|
||||
|
||||
|
||||
//additional style for arc42 help callouts
|
||||
ifdef::backend-html5[]
|
||||
++++
|
||||
<style>
|
||||
.arc42help {font-size:small; width: 14px; height: 16px; overflow: hidden; position: absolute; right: 0; padding: 2px 0 3px 2px;}
|
||||
.arc42help::before {content: "?";}
|
||||
.arc42help:hover {width:auto; height: auto; z-index: 100; padding: 10px;}
|
||||
.arc42help:hover::before {content: "";}
|
||||
@media print {
|
||||
.arc42help {display:none;}
|
||||
}
|
||||
</style>
|
||||
++++
|
||||
endif::backend-html5[]
|
||||
|
||||
|
||||
|
||||
// horizontal line
|
||||
***
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
[NOTE]
|
||||
====
|
||||
This version of the template contains some help and explanations.
|
||||
It is used for familiarization with arc42 and the understanding of the concepts.
|
||||
For documentation of your own system you use better the _plain_ version.
|
||||
====
|
||||
****
|
||||
|
||||
|
||||
// numbering from here on
|
||||
:numbered:
|
||||
|
||||
<<<<
|
||||
// 1. Introduction and Goals
|
||||
include::chapters/01_introduction_and_goals.adoc[]
|
||||
|
||||
<<<<
|
||||
// 2. Architecture Constraints
|
||||
include::chapters/02_architecture_constraints.adoc[]
|
||||
|
||||
<<<<
|
||||
// 3. System Scope and Context
|
||||
include::chapters/03_system_scope_and_context.adoc[]
|
||||
|
||||
<<<<
|
||||
// 4. Solution Strategy
|
||||
include::chapters/04_solution_strategy.adoc[]
|
||||
|
||||
<<<<
|
||||
// 5. Building Block View
|
||||
include::chapters/05_building_block_view.adoc[]
|
||||
|
||||
<<<<
|
||||
// 6. Runtime View
|
||||
include::chapters/06_runtime_view.adoc[]
|
||||
|
||||
<<<<
|
||||
// 7. Deployment View
|
||||
include::chapters/07_deployment_view.adoc[]
|
||||
|
||||
<<<<
|
||||
// 8. Concepts
|
||||
include::chapters/08_concepts.adoc[]
|
||||
|
||||
<<<<
|
||||
// 9. Architecture Decisions
|
||||
include::chapters/09_architecture_decisions.adoc[]
|
||||
|
||||
<<<<
|
||||
// 10. Quality Requirements
|
||||
include::chapters/10_quality_requirements.adoc[]
|
||||
|
||||
<<<<
|
||||
// 11. Technical Risks
|
||||
include::chapters/11_technical_risks.adoc[]
|
||||
|
||||
<<<<
|
||||
// 12. Glossary
|
||||
include::chapters/12_glossary.adoc[]
|
||||
2
src/arc42/chapters/.asciidoctorconfig.adoc
Normal file
2
src/arc42/chapters/.asciidoctorconfig.adoc
Normal file
|
|
@ -0,0 +1,2 @@
|
|||
:imagesdir: ../../images
|
||||
|
||||
103
src/arc42/chapters/01_introduction_and_goals.adoc
Normal file
103
src/arc42/chapters/01_introduction_and_goals.adoc
Normal file
|
|
@ -0,0 +1,103 @@
|
|||
:jbake-title: Introduction and Goals
|
||||
:jbake-type: page_toc
|
||||
:jbake-status: published
|
||||
:jbake-menu: arc42
|
||||
:jbake-order: 1
|
||||
:filename: /chapters/01_introduction_and_goals.adoc
|
||||
ifndef::imagesdir[:imagesdir: ../../images]
|
||||
|
||||
:toc:
|
||||
|
||||
ifndef::imagesdir[:imagesdir: ../images]
|
||||
|
||||
[[section-introduction-and-goals]]
|
||||
== Introduction and Goals
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
Describes the relevant requirements and the driving forces that software architects and development team must consider.
|
||||
These include
|
||||
|
||||
* underlying business goals,
|
||||
* essential features,
|
||||
* essential functional requirements,
|
||||
* quality goals for the architecture and
|
||||
* relevant stakeholders and their expectations
|
||||
****
|
||||
|
||||
=== Requirements Overview
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
.Contents
|
||||
Short description of the functional requirements, driving forces, extract (or abstract)
|
||||
of requirements. Link to (hopefully existing) requirements documents
|
||||
(with version number and information where to find it).
|
||||
|
||||
.Motivation
|
||||
From the point of view of the end users a system is created or modified to
|
||||
improve support of a business activity and/or improve the quality.
|
||||
|
||||
.Form
|
||||
Short textual description, probably in tabular use-case format.
|
||||
If requirements documents exist this overview should refer to these documents.
|
||||
|
||||
Keep these excerpts as short as possible. Balance readability of this document with potential redundancy w.r.t to requirements documents.
|
||||
|
||||
|
||||
.Further Information
|
||||
|
||||
See https://docs.arc42.org/section-1/[Introduction and Goals] in the arc42 documentation.
|
||||
|
||||
****
|
||||
|
||||
=== Quality Goals
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
.Contents
|
||||
The top three (max five) quality goals for the architecture whose fulfillment is of highest importance to the major stakeholders.
|
||||
We really mean quality goals for the architecture. Don't confuse them with project goals.
|
||||
They are not necessarily identical.
|
||||
|
||||
Consider this overview of potential topics (based upon the ISO 25010 standard):
|
||||
|
||||
image::01_2_iso-25010-topics-EN.drawio.png["Categories of Quality Requirements"]
|
||||
|
||||
.Motivation
|
||||
You should know the quality goals of your most important stakeholders, since they will influence fundamental architectural decisions.
|
||||
Make sure to be very concrete about these qualities, avoid buzzwords.
|
||||
If you as an architect do not know how the quality of your work will be judged...
|
||||
|
||||
.Form
|
||||
A table with quality goals and concrete scenarios, ordered by priorities
|
||||
****
|
||||
|
||||
=== Stakeholders
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
.Contents
|
||||
Explicit overview of stakeholders of the system, i.e. all person, roles or organizations that
|
||||
|
||||
* should know the architecture
|
||||
* have to be convinced of the architecture
|
||||
* have to work with the architecture or with code
|
||||
* need the documentation of the architecture for their work
|
||||
* have to come up with decisions about the system or its development
|
||||
|
||||
.Motivation
|
||||
You should know all parties involved in development of the system or affected by the system.
|
||||
Otherwise, you may get nasty surprises later in the development process.
|
||||
These stakeholders determine the extent and the level of detail of your work and its results.
|
||||
|
||||
.Form
|
||||
Table with role names, person names, and their expectations with respect to the architecture and its documentation.
|
||||
****
|
||||
|
||||
[options="header",cols="1,2,2"]
|
||||
|===
|
||||
|Role/Name|Contact|Expectations
|
||||
| _<Role-1>_ | _<Contact-1>_ | _<Expectation-1>_
|
||||
| _<Role-2>_ | _<Contact-2>_ | _<Expectation-2>_
|
||||
|===
|
||||
37
src/arc42/chapters/02_architecture_constraints.adoc
Normal file
37
src/arc42/chapters/02_architecture_constraints.adoc
Normal file
|
|
@ -0,0 +1,37 @@
|
|||
:jbake-title: Architecture Constraints
|
||||
:jbake-type: page_toc
|
||||
:jbake-status: published
|
||||
:jbake-menu: arc42
|
||||
:jbake-order: 2
|
||||
:filename: /chapters/02_architecture_constraints.adoc
|
||||
ifndef::imagesdir[:imagesdir: ../../images]
|
||||
|
||||
:toc:
|
||||
|
||||
ifndef::imagesdir[:imagesdir: ../images]
|
||||
|
||||
[[section-architecture-constraints]]
|
||||
== Architecture Constraints
|
||||
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
.Contents
|
||||
Any requirement that constraints software architects in their freedom of design and implementation decisions or decision about the development process. These constraints sometimes go beyond individual systems and are valid for whole organizations and companies.
|
||||
|
||||
.Motivation
|
||||
Architects should know exactly where they are free in their design decisions and where they must adhere to constraints.
|
||||
Constraints must always be dealt with; they may be negotiable, though.
|
||||
|
||||
.Form
|
||||
Simple tables of constraints with explanations.
|
||||
If needed you can subdivide them into
|
||||
technical constraints, organizational and political constraints and
|
||||
conventions (e.g. programming or versioning guidelines, documentation or naming conventions)
|
||||
|
||||
|
||||
.Further Information
|
||||
|
||||
See https://docs.arc42.org/section-2/[Architecture Constraints] in the arc42 documentation.
|
||||
|
||||
****
|
||||
107
src/arc42/chapters/03_system_scope_and_context.adoc
Normal file
107
src/arc42/chapters/03_system_scope_and_context.adoc
Normal file
|
|
@ -0,0 +1,107 @@
|
|||
:jbake-title: System Scope and Context
|
||||
:jbake-type: page_toc
|
||||
:jbake-status: published
|
||||
:jbake-menu: arc42
|
||||
:jbake-order: 3
|
||||
:filename: /chapters/03_system_scope_and_context.adoc
|
||||
ifndef::imagesdir[:imagesdir: ../../images]
|
||||
|
||||
:toc:
|
||||
|
||||
ifndef::imagesdir[:imagesdir: ../images]
|
||||
|
||||
[[section-system-scope-and-context]]
|
||||
== System Scope and Context
|
||||
|
||||
|
||||
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
.Contents
|
||||
System scope and context - as the name suggests - delimits your system (i.e. your scope) from all its communication partners
|
||||
(neighboring systems and users, i.e. the context of your system). It thereby specifies the external interfaces.
|
||||
|
||||
If necessary, differentiate the business context (domain specific inputs and outputs) from the technical context (channels, protocols, hardware).
|
||||
|
||||
.Motivation
|
||||
The domain interfaces and technical interfaces to communication partners are among your system's most critical aspects. Make sure that you completely understand them.
|
||||
|
||||
.Form
|
||||
Various options:
|
||||
|
||||
* Context diagrams
|
||||
* Lists of communication partners and their interfaces.
|
||||
|
||||
|
||||
.Further Information
|
||||
|
||||
See https://docs.arc42.org/section-3/[Context and Scope] in the arc42 documentation.
|
||||
|
||||
****
|
||||
|
||||
|
||||
=== Business Context
|
||||
|
||||
|
||||
image::03_business_context.svg["Business Context"]
|
||||
|
||||
[cols="1,1"]
|
||||
|===
|
||||
|System |description
|
||||
|
||||
|External System One
|
||||
|Some external system
|
||||
|
||||
|External System Two
|
||||
|Another external system
|
||||
|
||||
|System
|
||||
|the system itself
|
||||
|===
|
||||
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
.Contents
|
||||
Specification of *all* communication partners (users, IT-systems, ...) with explanations of domain specific inputs and outputs or interfaces.
|
||||
Optionally you can add domain specific formats or communication protocols.
|
||||
|
||||
.Motivation
|
||||
All stakeholders should understand which data are exchanged with the environment of the system.
|
||||
|
||||
.Form
|
||||
All kinds of diagrams that show the system as a black box and specify the domain interfaces to communication partners.
|
||||
|
||||
Alternatively (or additionally) you can use a table.
|
||||
The title of the table is the name of your system, the three columns contain the name of the communication partner, the inputs, and the outputs.
|
||||
|
||||
****
|
||||
|
||||
**<Diagram or Table>**
|
||||
|
||||
**<optionally: Explanation of external domain interfaces>**
|
||||
|
||||
=== Technical Context
|
||||
|
||||
image::03_technical_context.svg["Technical Context"]
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
.Contents
|
||||
Technical interfaces (channels and transmission media) linking your system to its environment. In addition a mapping of domain specific input/output to the channels, i.e. an explanation which I/O uses which channel.
|
||||
|
||||
.Motivation
|
||||
Many stakeholders make architectural decision based on the technical interfaces between the system and its context. Especially infrastructure or hardware designers decide these technical interfaces.
|
||||
|
||||
.Form
|
||||
E.g. UML deployment diagram describing channels to neighboring systems,
|
||||
together with a mapping table showing the relationships between channels and input/output.
|
||||
|
||||
****
|
||||
|
||||
**<Diagram or Table>**
|
||||
|
||||
**<optionally: Explanation of technical interfaces>**
|
||||
|
||||
**<Mapping Input/Output to Channels>**
|
||||
42
src/arc42/chapters/04_solution_strategy.adoc
Normal file
42
src/arc42/chapters/04_solution_strategy.adoc
Normal file
|
|
@ -0,0 +1,42 @@
|
|||
:jbake-title: Solution Strategy
|
||||
:jbake-type: page_toc
|
||||
:jbake-status: published
|
||||
:jbake-menu: arc42
|
||||
:jbake-order: 4
|
||||
:filename: /chapters/04_solution_strategy.adoc
|
||||
ifndef::imagesdir[:imagesdir: ../../images]
|
||||
|
||||
:toc:
|
||||
|
||||
ifndef::imagesdir[:imagesdir: ../images]
|
||||
|
||||
[[section-solution-strategy]]
|
||||
== Solution Strategy
|
||||
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
.Contents
|
||||
A short summary and explanation of the fundamental decisions and solution strategies, that shape system architecture. It includes
|
||||
|
||||
* technology decisions
|
||||
* decisions about the top-level decomposition of the system, e.g. usage of an architectural pattern or design pattern
|
||||
* decisions on how to achieve key quality goals
|
||||
* relevant organizational decisions, e.g. selecting a development process or delegating certain tasks to third parties.
|
||||
|
||||
.Motivation
|
||||
These decisions form the cornerstones for your architecture. They are the foundation for many other detailed decisions or implementation rules.
|
||||
|
||||
.Form
|
||||
Keep the explanations of such key decisions short.
|
||||
|
||||
Motivate what was decided and why it was decided that way,
|
||||
based upon problem statement, quality goals and key constraints.
|
||||
Refer to details in the following sections.
|
||||
|
||||
|
||||
.Further Information
|
||||
|
||||
See https://docs.arc42.org/section-4/[Solution Strategy] in the arc42 documentation.
|
||||
|
||||
****
|
||||
222
src/arc42/chapters/05_building_block_view.adoc
Normal file
222
src/arc42/chapters/05_building_block_view.adoc
Normal file
|
|
@ -0,0 +1,222 @@
|
|||
:jbake-title: Building Block View
|
||||
:jbake-type: page_toc
|
||||
:jbake-status: published
|
||||
:jbake-menu: arc42
|
||||
:jbake-order: 5
|
||||
:filename: /chapters/05_building_block_view.adoc
|
||||
ifndef::imagesdir[:imagesdir: ../../images]
|
||||
|
||||
:toc:
|
||||
|
||||
ifndef::imagesdir[:imagesdir: ../images]
|
||||
|
||||
[[section-building-block-view]]
|
||||
|
||||
|
||||
== Building Block View
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
.Content
|
||||
The building block view shows the static decomposition of the system into building blocks (modules, components, subsystems, classes, interfaces, packages, libraries, frameworks, layers, partitions, tiers, functions, macros, operations, data structures, ...) as well as their dependencies (relationships, associations, ...)
|
||||
|
||||
This view is mandatory for every architecture documentation.
|
||||
In analogy to a house this is the _floor plan_.
|
||||
|
||||
.Motivation
|
||||
Maintain an overview of your source code by making its structure understandable through
|
||||
abstraction.
|
||||
|
||||
This allows you to communicate with your stakeholder on an abstract level without disclosing implementation details.
|
||||
|
||||
.Form
|
||||
The building block view is a hierarchical collection of black boxes and white boxes
|
||||
(see figure below) and their descriptions.
|
||||
|
||||
image::05_building_blocks-EN.png["Hierarchy of building blocks"]
|
||||
|
||||
*Level 1* is the white box description of the overall system together with black
|
||||
box descriptions of all contained building blocks.
|
||||
|
||||
*Level 2* zooms into some building blocks of level 1.
|
||||
Thus it contains the white box description of selected building blocks of level 1, together with black box descriptions of their internal building blocks.
|
||||
|
||||
*Level 3* zooms into selected building blocks of level 2, and so on.
|
||||
|
||||
|
||||
.Further Information
|
||||
|
||||
See https://docs.arc42.org/section-5/[Building Block View] in the arc42 documentation.
|
||||
|
||||
****
|
||||
|
||||
=== Whitebox Overall System
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
Here you describe the decomposition of the overall system using the following white box template. It contains
|
||||
|
||||
* an overview diagram
|
||||
* a motivation for the decomposition
|
||||
* black box descriptions of the contained building blocks. For these we offer you alternatives:
|
||||
|
||||
** use _one_ table for a short and pragmatic overview of all contained building blocks and their interfaces
|
||||
** use a list of black box descriptions of the building blocks according to the black box template (see below).
|
||||
Depending on your choice of tool this list could be sub-chapters (in text files), sub-pages (in a Wiki) or nested elements (in a modeling tool).
|
||||
|
||||
|
||||
* (optional:) important interfaces, that are not explained in the black box templates of a building block, but are very important for understanding the white box.
|
||||
Since there are so many ways to specify interfaces why do not provide a specific template for them.
|
||||
In the worst case you have to specify and describe syntax, semantics, protocols, error handling,
|
||||
restrictions, versions, qualities, necessary compatibilities and many things more.
|
||||
In the best case you will get away with examples or simple signatures.
|
||||
|
||||
****
|
||||
|
||||
_**<Overview Diagram>**_
|
||||
|
||||
Motivation::
|
||||
|
||||
_<text explanation>_
|
||||
|
||||
|
||||
Contained Building Blocks::
|
||||
_<Description of contained building block (black boxes)>_
|
||||
|
||||
Important Interfaces::
|
||||
_<Description of important interfaces>_
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
Insert your explanations of black boxes from level 1:
|
||||
|
||||
If you use tabular form you will only describe your black boxes with name and
|
||||
responsibility according to the following schema:
|
||||
|
||||
[cols="1,2" options="header"]
|
||||
|===
|
||||
| **Name** | **Responsibility**
|
||||
| _<black box 1>_ | _<Text>_
|
||||
| _<black box 2>_ | _<Text>_
|
||||
|===
|
||||
|
||||
|
||||
|
||||
If you use a list of black box descriptions then you fill in a separate black box template for every important building block .
|
||||
Its headline is the name of the black box.
|
||||
****
|
||||
|
||||
|
||||
==== <Name black box 1>
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
Here you describe <black box 1>
|
||||
according the the following black box template:
|
||||
|
||||
* Purpose/Responsibility
|
||||
* Interface(s), when they are not extracted as separate paragraphs. This interfaces may include qualities and performance characteristics.
|
||||
* (Optional) Quality-/Performance characteristics of the black box, e.g.availability, run time behavior, ....
|
||||
* (Optional) directory/file location
|
||||
* (Optional) Fulfilled requirements (if you need traceability to requirements).
|
||||
* (Optional) Open issues/problems/risks
|
||||
|
||||
****
|
||||
|
||||
_<Purpose/Responsibility>_
|
||||
|
||||
_<Interface(s)>_
|
||||
|
||||
_<(Optional) Quality/Performance Characteristics>_
|
||||
|
||||
_<(Optional) Directory/File Location>_
|
||||
|
||||
_<(Optional) Fulfilled Requirements>_
|
||||
|
||||
_<(optional) Open Issues/Problems/Risks>_
|
||||
|
||||
|
||||
|
||||
|
||||
==== <Name black box 2>
|
||||
|
||||
_<black box template>_
|
||||
|
||||
==== <Name black box n>
|
||||
|
||||
_<black box template>_
|
||||
|
||||
|
||||
==== <Name interface 1>
|
||||
|
||||
...
|
||||
|
||||
==== <Name interface m>
|
||||
|
||||
|
||||
|
||||
=== Level 2
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
Here you can specify the inner structure of (some) building blocks from level 1 as white boxes.
|
||||
|
||||
You have to decide which building blocks of your system are important enough to justify such a detailed description.
|
||||
Please prefer relevance over completeness. Specify important, surprising, risky, complex or volatile building blocks.
|
||||
Leave out normal, simple, boring or standardized parts of your system
|
||||
****
|
||||
|
||||
==== White Box _<building block 1>_
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
...describes the internal structure of _building block 1_.
|
||||
****
|
||||
|
||||
_<white box template>_
|
||||
|
||||
==== White Box _<building block 2>_
|
||||
|
||||
|
||||
_<white box template>_
|
||||
|
||||
...
|
||||
|
||||
==== White Box _<building block m>_
|
||||
|
||||
|
||||
_<white box template>_
|
||||
|
||||
|
||||
|
||||
=== Level 3
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
Here you can specify the inner structure of (some) building blocks from level 2 as white boxes.
|
||||
|
||||
When you need more detailed levels of your architecture please copy this
|
||||
part of arc42 for additional levels.
|
||||
****
|
||||
|
||||
|
||||
==== White Box <_building block x.1_>
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
Specifies the internal structure of _building block x.1_.
|
||||
****
|
||||
|
||||
|
||||
_<white box template>_
|
||||
|
||||
|
||||
==== White Box <_building block x.2_>
|
||||
|
||||
_<white box template>_
|
||||
|
||||
|
||||
|
||||
==== White Box <_building block y.1_>
|
||||
|
||||
_<white box template>_
|
||||
61
src/arc42/chapters/06_runtime_view.adoc
Normal file
61
src/arc42/chapters/06_runtime_view.adoc
Normal file
|
|
@ -0,0 +1,61 @@
|
|||
:jbake-title: Runtime View
|
||||
:jbake-type: page_toc
|
||||
:jbake-status: published
|
||||
:jbake-menu: arc42
|
||||
:jbake-order: 6
|
||||
:filename: /chapters/06_runtime_view.adoc
|
||||
ifndef::imagesdir[:imagesdir: ../../images]
|
||||
|
||||
:toc:
|
||||
|
||||
ifndef::imagesdir[:imagesdir: ../images]
|
||||
|
||||
[[section-runtime-view]]
|
||||
== Runtime View
|
||||
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
.Contents
|
||||
The runtime view describes concrete behavior and interactions of the system’s building blocks in form of scenarios from the following areas:
|
||||
|
||||
* important use cases or features: how do building blocks execute them?
|
||||
* interactions at critical external interfaces: how do building blocks cooperate with users and neighboring systems?
|
||||
* operation and administration: launch, start-up, stop
|
||||
* error and exception scenarios
|
||||
|
||||
Remark: The main criterion for the choice of possible scenarios (sequences, workflows) is their *architectural relevance*. It is *not* important to describe a large number of scenarios. You should rather document a representative selection.
|
||||
|
||||
.Motivation
|
||||
You should understand how (instances of) building blocks of your system perform their job and communicate at runtime.
|
||||
You will mainly capture scenarios in your documentation to communicate your architecture to stakeholders that are less willing or able to read and understand the static models (building block view, deployment view).
|
||||
|
||||
.Form
|
||||
There are many notations for describing scenarios, e.g.
|
||||
|
||||
* numbered list of steps (in natural language)
|
||||
* activity diagrams or flow charts
|
||||
* sequence diagrams
|
||||
* BPMN or EPCs (event process chains)
|
||||
* state machines
|
||||
* ...
|
||||
|
||||
|
||||
.Further Information
|
||||
|
||||
See https://docs.arc42.org/section-6/[Runtime View] in the arc42 documentation.
|
||||
|
||||
****
|
||||
|
||||
=== <Runtime Scenario 1>
|
||||
|
||||
|
||||
* _<insert runtime diagram or textual description of the scenario>_
|
||||
* _<insert description of the notable aspects of the interactions between the
|
||||
building block instances depicted in this diagram.>_
|
||||
|
||||
=== <Runtime Scenario 2>
|
||||
|
||||
=== ...
|
||||
|
||||
=== <Runtime Scenario n>
|
||||
104
src/arc42/chapters/07_deployment_view.adoc
Normal file
104
src/arc42/chapters/07_deployment_view.adoc
Normal file
|
|
@ -0,0 +1,104 @@
|
|||
:jbake-title: Deployment View
|
||||
:jbake-type: page_toc
|
||||
:jbake-status: published
|
||||
:jbake-menu: arc42
|
||||
:jbake-order: 7
|
||||
:filename: /chapters/07_deployment_view.adoc
|
||||
ifndef::imagesdir[:imagesdir: ../../images]
|
||||
|
||||
:toc:
|
||||
|
||||
ifndef::imagesdir[:imagesdir: ../images]
|
||||
|
||||
[[section-deployment-view]]
|
||||
|
||||
|
||||
== Deployment View
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
.Content
|
||||
The deployment view describes:
|
||||
|
||||
1. technical infrastructure used to execute your system, with infrastructure elements like geographical locations, environments, computers, processors, channels and net topologies as well as other infrastructure elements and
|
||||
|
||||
2. mapping of (software) building blocks to that infrastructure elements.
|
||||
|
||||
Often systems are executed in different environments, e.g. development environment, test environment, production environment. In such cases you should document all relevant environments.
|
||||
|
||||
Especially document a deployment view if your software is executed as distributed system with more than one computer, processor, server or container or when you design and construct your own hardware processors and chips.
|
||||
|
||||
From a software perspective it is sufficient to capture only those elements of an infrastructure that are needed to show a deployment of your building blocks. Hardware architects can go beyond that and describe an infrastructure to any level of detail they need to capture.
|
||||
|
||||
.Motivation
|
||||
Software does not run without hardware.
|
||||
This underlying infrastructure can and will influence a system and/or some
|
||||
cross-cutting concepts. Therefore, there is a need to know the infrastructure.
|
||||
|
||||
.Form
|
||||
|
||||
Maybe a highest level deployment diagram is already contained in section 3.2. as
|
||||
technical context with your own infrastructure as ONE black box. In this section one can
|
||||
zoom into this black box using additional deployment diagrams:
|
||||
|
||||
* UML offers deployment diagrams to express that view. Use it, probably with nested diagrams,
|
||||
when your infrastructure is more complex.
|
||||
* When your (hardware) stakeholders prefer other kinds of diagrams rather than a deployment diagram, let them use any kind that is able to show nodes and channels of the infrastructure.
|
||||
|
||||
|
||||
.Further Information
|
||||
|
||||
See https://docs.arc42.org/section-7/[Deployment View] in the arc42 documentation.
|
||||
|
||||
****
|
||||
|
||||
=== Infrastructure Level 1
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
Describe (usually in a combination of diagrams, tables, and text):
|
||||
|
||||
* distribution of a system to multiple locations, environments, computers, processors, .., as well as physical connections between them
|
||||
* important justifications or motivations for this deployment structure
|
||||
* quality and/or performance features of this infrastructure
|
||||
* mapping of software artifacts to elements of this infrastructure
|
||||
|
||||
For multiple environments or alternative deployments please copy and adapt this section of arc42 for all relevant environments.
|
||||
****
|
||||
|
||||
_**<Overview Diagram>**_
|
||||
|
||||
Motivation::
|
||||
|
||||
_<explanation in text form>_
|
||||
|
||||
Quality and/or Performance Features::
|
||||
|
||||
_<explanation in text form>_
|
||||
|
||||
Mapping of Building Blocks to Infrastructure::
|
||||
_<description of the mapping>_
|
||||
|
||||
|
||||
=== Infrastructure Level 2
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
Here you can include the internal structure of (some) infrastructure elements from level 1.
|
||||
|
||||
Please copy the structure from level 1 for each selected element.
|
||||
****
|
||||
|
||||
==== _<Infrastructure Element 1>_
|
||||
|
||||
_<diagram + explanation>_
|
||||
|
||||
==== _<Infrastructure Element 2>_
|
||||
|
||||
_<diagram + explanation>_
|
||||
|
||||
...
|
||||
|
||||
==== _<Infrastructure Element n>_
|
||||
|
||||
_<diagram + explanation>_
|
||||
83
src/arc42/chapters/08_concepts.adoc
Normal file
83
src/arc42/chapters/08_concepts.adoc
Normal file
|
|
@ -0,0 +1,83 @@
|
|||
:jbake-title: Cross-cutting Concepts
|
||||
:jbake-type: page_toc
|
||||
:jbake-status: published
|
||||
:jbake-menu: arc42
|
||||
:jbake-order: 8
|
||||
:filename: /chapters/08_concepts.adoc
|
||||
ifndef::imagesdir[:imagesdir: ../../images]
|
||||
|
||||
:toc:
|
||||
|
||||
ifndef::imagesdir[:imagesdir: ../images]
|
||||
|
||||
[[section-concepts]]
|
||||
== Cross-cutting Concepts
|
||||
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
.Content
|
||||
This section describes overall, principal regulations and solution ideas that are relevant in multiple parts (= cross-cutting) of your system.
|
||||
Such concepts are often related to multiple building blocks.
|
||||
They can include many different topics, such as
|
||||
|
||||
* models, especially domain models
|
||||
* architecture or design patterns
|
||||
* rules for using specific technology
|
||||
* principal, often technical decisions of an overarching (= cross-cutting) nature
|
||||
* implementation rules
|
||||
|
||||
|
||||
.Motivation
|
||||
Concepts form the basis for _conceptual integrity_ (consistency, homogeneity) of the architecture.
|
||||
Thus, they are an important contribution to achieve inner qualities of your system.
|
||||
|
||||
Some of these concepts cannot be assigned to individual building blocks, e.g. security or safety.
|
||||
|
||||
|
||||
.Form
|
||||
The form can be varied:
|
||||
|
||||
* concept papers with any kind of structure
|
||||
* cross-cutting model excerpts or scenarios using notations of the architecture views
|
||||
* sample implementations, especially for technical concepts
|
||||
* reference to typical usage of standard frameworks (e.g. using Hibernate for object/relational mapping)
|
||||
|
||||
.Structure
|
||||
A potential (but not mandatory) structure for this section could be:
|
||||
|
||||
* Domain concepts
|
||||
* User Experience concepts (UX)
|
||||
* Safety and security concepts
|
||||
* Architecture and design patterns
|
||||
* "Under-the-hood"
|
||||
* development concepts
|
||||
* operational concepts
|
||||
|
||||
Note: it might be difficult to assign individual concepts to one specific topic
|
||||
on this list.
|
||||
|
||||
image::08-Crosscutting-Concepts-Structure-EN.png["Possible topics for crosscutting concepts"]
|
||||
|
||||
|
||||
.Further Information
|
||||
|
||||
See https://docs.arc42.org/section-8/[Concepts] in the arc42 documentation.
|
||||
****
|
||||
|
||||
|
||||
=== _<Concept 1>_
|
||||
|
||||
_<explanation>_
|
||||
|
||||
|
||||
|
||||
=== _<Concept 2>_
|
||||
|
||||
_<explanation>_
|
||||
|
||||
...
|
||||
|
||||
=== _<Concept n>_
|
||||
|
||||
_<explanation>_
|
||||
48
src/arc42/chapters/09_architecture_decisions.adoc
Normal file
48
src/arc42/chapters/09_architecture_decisions.adoc
Normal file
|
|
@ -0,0 +1,48 @@
|
|||
:jbake-title: Architecture Decisions
|
||||
:jbake-type: page_toc
|
||||
:jbake-status: published
|
||||
:jbake-menu: arc42
|
||||
:jbake-order: 9
|
||||
:filename: /chapters/09_architecture_decisions.adoc
|
||||
ifndef::imagesdir[:imagesdir: ../../images]
|
||||
|
||||
:toc:
|
||||
|
||||
ifndef::imagesdir[:imagesdir: ../images]
|
||||
|
||||
[[section-design-decisions]]
|
||||
== Architecture Decisions
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
.Contents
|
||||
Important, expensive, large scale or risky architecture decisions including rationales.
|
||||
With "decisions" we mean selecting one alternative based on given criteria.
|
||||
|
||||
Please use your judgement to decide whether an architectural decision should be documented
|
||||
here in this central section or whether you better document it locally
|
||||
(e.g. within the white box template of one building block).
|
||||
|
||||
Avoid redundancy.
|
||||
Refer to section 4, where you already captured the most important decisions of your architecture.
|
||||
|
||||
.Motivation
|
||||
Stakeholders of your system should be able to comprehend and retrace your decisions.
|
||||
|
||||
.Form
|
||||
Various options:
|
||||
|
||||
* ADR (https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions[Documenting Architecture Decisions]) for every important decision
|
||||
* List or table, ordered by importance and consequences or:
|
||||
* more detailed in form of separate sections per decision
|
||||
|
||||
.Further Information
|
||||
|
||||
See https://docs.arc42.org/section-9/[Architecture Decisions] in the arc42 documentation.
|
||||
There you will find links and examples about ADR.
|
||||
|
||||
****
|
||||
|
||||
include::adr/0001-use-d2-as-diagram-modelling-tool.adoc[]
|
||||
|
||||
include::adr/0002-use-asciidoc-for-writing-documentation-with-arc42.adoc[]
|
||||
87
src/arc42/chapters/10_quality_requirements.adoc
Normal file
87
src/arc42/chapters/10_quality_requirements.adoc
Normal file
|
|
@ -0,0 +1,87 @@
|
|||
:jbake-title: Quality Requirements
|
||||
:jbake-type: page_toc
|
||||
:jbake-status: published
|
||||
:jbake-menu: arc42
|
||||
:jbake-order: 10
|
||||
:filename: /chapters/10_quality_requirements.adoc
|
||||
ifndef::imagesdir[:imagesdir: ../../images]
|
||||
|
||||
:toc:
|
||||
|
||||
ifndef::imagesdir[:imagesdir: ../images]
|
||||
|
||||
[[section-quality-scenarios]]
|
||||
== Quality Requirements
|
||||
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
|
||||
.Content
|
||||
This section contains all quality requirements as quality tree with scenarios. The most important ones have already been described in section 1.2. (quality goals)
|
||||
|
||||
Here you can also capture quality requirements with lesser priority,
|
||||
which will not create high risks when they are not fully achieved.
|
||||
|
||||
.Motivation
|
||||
Since quality requirements will have a lot of influence on architectural
|
||||
decisions you should know for every stakeholder what is really important to them,
|
||||
concrete and measurable.
|
||||
|
||||
|
||||
.Further Information
|
||||
|
||||
See https://docs.arc42.org/section-10/[Quality Requirements] in the arc42 documentation.
|
||||
|
||||
****
|
||||
|
||||
=== Quality Tree
|
||||
|
||||
|
||||
image::10_quality_tree.svg["Quality tree"]
|
||||
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
.Content
|
||||
The quality tree (as defined in ATAM – Architecture Tradeoff Analysis Method) with quality/evaluation scenarios as leafs.
|
||||
|
||||
.Motivation
|
||||
The tree structure with priorities provides an overview for a sometimes large number of quality requirements.
|
||||
|
||||
.Form
|
||||
The quality tree is a high-level overview of the quality goals and requirements:
|
||||
|
||||
* tree-like refinement of the term "quality". Use "quality" or "usefulness" as a root
|
||||
* a mind map with quality categories as main branches
|
||||
|
||||
In any case the tree should include links to the scenarios of the following section.
|
||||
|
||||
|
||||
****
|
||||
|
||||
=== Quality Scenarios
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
.Contents
|
||||
Concretization of (sometimes vague or implicit) quality requirements using (quality) scenarios.
|
||||
|
||||
These scenarios describe what should happen when a stimulus arrives at the system.
|
||||
|
||||
For architects, two kinds of scenarios are important:
|
||||
|
||||
* Usage scenarios (also called application scenarios or use case scenarios) describe the system’s runtime reaction to a certain stimulus. This also includes scenarios that describe the system’s efficiency or performance. Example: The system reacts to a user’s request within one second.
|
||||
* Change scenarios describe a modification of the system or of its immediate environment. Example: Additional functionality is implemented or requirements for a quality attribute change.
|
||||
|
||||
.Motivation
|
||||
Scenarios make quality requirements concrete and allow to
|
||||
more easily measure or decide whether they are fulfilled.
|
||||
|
||||
Especially when you want to assess your architecture using methods like
|
||||
ATAM you need to describe your quality goals (from section 1.2)
|
||||
more precisely down to a level of scenarios that can be discussed and evaluated.
|
||||
|
||||
.Form
|
||||
Tabular or free form text.
|
||||
****
|
||||
35
src/arc42/chapters/11_technical_risks.adoc
Normal file
35
src/arc42/chapters/11_technical_risks.adoc
Normal file
|
|
@ -0,0 +1,35 @@
|
|||
:jbake-title: Risks and Technical Debts
|
||||
:jbake-type: page_toc
|
||||
:jbake-status: published
|
||||
:jbake-menu: arc42
|
||||
:jbake-order: 11
|
||||
:filename: /chapters/11_technical_risks.adoc
|
||||
ifndef::imagesdir[:imagesdir: ../../images]
|
||||
|
||||
:toc:
|
||||
|
||||
ifndef::imagesdir[:imagesdir: ../images]
|
||||
|
||||
[[section-technical-risks]]
|
||||
== Risks and Technical Debts
|
||||
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
.Contents
|
||||
A list of identified technical risks or technical debts, ordered by priority
|
||||
|
||||
.Motivation
|
||||
“Risk management is project management for grown-ups” (Tim Lister, Atlantic Systems Guild.)
|
||||
|
||||
This should be your motto for systematic detection and evaluation of risks and technical debts in the architecture, which will be needed by management stakeholders (e.g. project managers, product owners) as part of the overall risk analysis and measurement planning.
|
||||
|
||||
.Form
|
||||
List of risks and/or technical debts, probably including suggested measures to minimize, mitigate or avoid risks or reduce technical debts.
|
||||
|
||||
|
||||
.Further Information
|
||||
|
||||
See https://docs.arc42.org/section-11/[Risks and Technical Debt] in the arc42 documentation.
|
||||
|
||||
****
|
||||
52
src/arc42/chapters/12_glossary.adoc
Normal file
52
src/arc42/chapters/12_glossary.adoc
Normal file
|
|
@ -0,0 +1,52 @@
|
|||
:jbake-title: Glossary
|
||||
:jbake-type: page_toc
|
||||
:jbake-status: published
|
||||
:jbake-menu: arc42
|
||||
:jbake-order: 12
|
||||
:filename: /chapters/12_glossary.adoc
|
||||
ifndef::imagesdir[:imagesdir: ../../images]
|
||||
|
||||
:toc:
|
||||
|
||||
ifndef::imagesdir[:imagesdir: ../images]
|
||||
|
||||
[[section-glossary]]
|
||||
== Glossary
|
||||
|
||||
[role="arc42help"]
|
||||
****
|
||||
.Contents
|
||||
The most important domain and technical terms that your stakeholders use when discussing the system.
|
||||
|
||||
You can also see the glossary as source for translations if you work in multi-language teams.
|
||||
|
||||
.Motivation
|
||||
You should clearly define your terms, so that all stakeholders
|
||||
|
||||
* have an identical understanding of these terms
|
||||
* do not use synonyms and homonyms
|
||||
|
||||
|
||||
.Form
|
||||
|
||||
A table with columns <Term> and <Definition>.
|
||||
|
||||
Potentially more columns in case you need translations.
|
||||
|
||||
|
||||
.Further Information
|
||||
|
||||
See https://docs.arc42.org/section-12/[Glossary] in the arc42 documentation.
|
||||
|
||||
****
|
||||
|
||||
[cols="e,2e" options="header"]
|
||||
|===
|
||||
|Term |Definition
|
||||
|
||||
|<Term-1>
|
||||
|<definition-1>
|
||||
|
||||
|<Term-2>
|
||||
|<definition-2>
|
||||
|===
|
||||
15
src/arc42/chapters/about-arc42.adoc
Normal file
15
src/arc42/chapters/about-arc42.adoc
Normal file
|
|
@ -0,0 +1,15 @@
|
|||
:homepage: https://arc42.org
|
||||
|
||||
:keywords: software-architecture, documentation, template, arc42
|
||||
|
||||
:numbered!:
|
||||
**About arc42**
|
||||
|
||||
[role="lead"]
|
||||
arc42, the template for documentation of software and system architecture.
|
||||
|
||||
Template Version {revnumber}. {revremark}, {revdate}
|
||||
|
||||
Created, maintained and (C) by Dr. Peter Hruschka, Dr. Gernot Starke and contributors.
|
||||
See https://arc42.org.
|
||||
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
=== 1. Use D2 as diagram modelling tool
|
||||
|
||||
Date: 2023-06-12
|
||||
|
||||
==== Status
|
||||
|
||||
Accepted
|
||||
|
||||
==== Decision makers
|
||||
|
||||
* Richard Heininger
|
||||
* Stephan Weißenberger
|
||||
|
||||
==== Context
|
||||
|
||||
All diagrams in the documentation should be accessible as code in a non proprierty way. All changes to a diagram should be traceable so everything can be reviewed and tracked using a version control system. We decided between `PlantUML` and `D2` as modelling languages. `PlantUML` is widely used and a foolproof ecosystem in almost every IDE available relying on `Java. `D2` is a new and modern approach written entirely in Go.
|
||||
|
||||
==== Decision
|
||||
|
||||
We decided to favor `D2` over `PlantUML` because of a much smaller footprint of the tool, a much faster generation of diagrams and overall many supported diagram types and more supported output formats.
|
||||
|
||||
==== Consequences
|
||||
|
||||
As of today, we rarely used `PlantUML` in any documentation, so the impact in migration is neglectible. Due to `D2` being very new the featureset could still change every day and is considered less stable. Current `PlantUML` diagrams do not need to be updated, but it would be highly appreciated to do so.
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
=== 2. Use AsciiDoc for writing documentation in arc42
|
||||
|
||||
Date: 2023-06-12
|
||||
|
||||
==== Status
|
||||
|
||||
Accepted
|
||||
|
||||
==== Decision makers
|
||||
|
||||
* Richard Heininger
|
||||
* Stephan Weißenberger
|
||||
|
||||
==== Context
|
||||
|
||||
Software should be documented in a widely used and standardized way. We use `arc42` this format. For writing the documentation we had to decide between `markdown` and `asciidoc`. `markdown` is a widely known easy to understand format and is readable without a renderer, it lacks configuration for text. `asciidoc` on the other hand has a great configuration for text, is standardized and a many different plugins to support basically everything.
|
||||
|
||||
==== Decision
|
||||
|
||||
We decided to favor `asciidoc` over `markdown` because it is standardized, has more features while being almost as simple as `markdown`.
|
||||
|
||||
==== Consequences
|
||||
|
||||
As of today, we rarely used `markdown` in any documentation, so the impact in migration is neglectible. Current `markdown` documentation does not need to be updated, but it would be highly appreciated to do so.
|
||||
9
src/arc42/chapters/config.adoc
Normal file
9
src/arc42/chapters/config.adoc
Normal file
|
|
@ -0,0 +1,9 @@
|
|||
// asciidoc settings for EN (English)
|
||||
// ==================================
|
||||
:toc-title: table of contents
|
||||
|
||||
// enable table-of-contents
|
||||
:toc:
|
||||
|
||||
// where are images located?
|
||||
:imagesdir: ../images
|
||||
9
src/diagrams/03_business_context.d2
Normal file
9
src/diagrams/03_business_context.d2
Normal file
|
|
@ -0,0 +1,9 @@
|
|||
system: The whole system
|
||||
|
||||
externalSystemOne: External System
|
||||
externalSystemOne.shape: cloud
|
||||
|
||||
externalSystemTwo: External System
|
||||
|
||||
externalSystemOne -> System
|
||||
system -> externalSystemTwo: updates some records
|
||||
9
src/diagrams/03_technical_context.d2
Normal file
9
src/diagrams/03_technical_context.d2
Normal file
|
|
@ -0,0 +1,9 @@
|
|||
system: The whole system
|
||||
|
||||
externalSystemOne: External System
|
||||
externalSystemOne.shape: cloud
|
||||
|
||||
externalSystemTwo: External System
|
||||
|
||||
externalSystemOne -> System: https
|
||||
system -> externalSystemTwo: https
|
||||
101
src/diagrams/10_quality_tree.d2
Normal file
101
src/diagrams/10_quality_tree.d2
Normal file
|
|
@ -0,0 +1,101 @@
|
|||
direction: right
|
||||
|
||||
Quality: "Software product quality"
|
||||
|
||||
# 1. level goals
|
||||
FunctionalSuitability: "Functional suitability"
|
||||
PerformanceEfficiency: "Performance efficiency"
|
||||
Usability
|
||||
Compatibility
|
||||
Reliability
|
||||
Security
|
||||
Maintainability
|
||||
Portability
|
||||
Quality -> FunctionalSuitability
|
||||
Quality -> PerformanceEfficiency
|
||||
Quality -> Usability
|
||||
Quality -> Compatibility
|
||||
Quality -> Reliability
|
||||
Quality -> Security
|
||||
Quality -> Maintainability
|
||||
Quality -> Portability
|
||||
|
||||
# 2. level goals for FunctionalSuitability
|
||||
FunctionalCompleteness: "Functional completeness"
|
||||
FunctionalCorrectness: "Functional correctness"
|
||||
FunctionalAppropriateness: "Functional appropriateness"
|
||||
FunctionalSuitability -> FunctionalCompleteness
|
||||
FunctionalSuitability -> FunctionalCorrectness
|
||||
FunctionalSuitability -> FunctionalAppropriateness
|
||||
|
||||
# 2. level goals for PerformanceEfficiency
|
||||
TimeBehaviour: "Time behaviour"
|
||||
ResourceUtilization: "Resource utilization"
|
||||
Capacity
|
||||
PerformanceEfficiency -> TimeBehaviour
|
||||
PerformanceEfficiency -> ResourceUtilization
|
||||
PerformanceEfficiency -> Capacity
|
||||
|
||||
# 2. level goals for Compatibility
|
||||
CoExistence: "Co Existence"
|
||||
Interoperability
|
||||
Compatibility -> CoExistence
|
||||
Compatibility -> Interoperability
|
||||
|
||||
# 2. level goals for Usability
|
||||
AppropriatenessRecognizability: "Appropriateness recognizability"
|
||||
Learnability
|
||||
Operability
|
||||
UserErrorProtection: "User error protection"
|
||||
UserInterfaceAesthetics: "User interface aesthetics"
|
||||
Accessibility
|
||||
Usability -> AppropriatenessRecognizability
|
||||
Usability -> Learnability
|
||||
Usability -> Operability
|
||||
Usability -> UserErrorProtection
|
||||
Usability -> UserInterfaceAesthetics
|
||||
Usability -> Accessibility
|
||||
|
||||
# 2. level goals for Reliability
|
||||
Maturity
|
||||
Availability
|
||||
FaultTolerance: "Fault tolerance"
|
||||
Recoverability
|
||||
Reliability -> Maturity
|
||||
Reliability -> Availability
|
||||
Reliability -> FaultTolerance
|
||||
Reliability -> Recoverability
|
||||
|
||||
# 2. level goals for Security
|
||||
Confidentiality
|
||||
Integrity
|
||||
NonRepudiation: "Non-repudiation"
|
||||
Accountability
|
||||
Authenticity
|
||||
Security -> Confidentiality
|
||||
Security -> Integrity
|
||||
Security -> NonRepudiation
|
||||
Security -> Accountability
|
||||
Security -> Authenticity
|
||||
|
||||
# 2. level goals for Maintainability
|
||||
Modularity
|
||||
Reusability
|
||||
Analysability
|
||||
Modifiability
|
||||
Testability
|
||||
Maintainability -> Modularity
|
||||
Maintainability -> Reusability
|
||||
Maintainability -> Analysability
|
||||
Maintainability -> Modifiability
|
||||
Maintainability -> Testability
|
||||
|
||||
# 2. level goals for Portability
|
||||
Adaptability
|
||||
Installability
|
||||
Replaceability
|
||||
Portability -> Adaptability
|
||||
Portability -> Installability
|
||||
Portability -> Replaceability
|
||||
|
||||
|
||||
17
src/diagrams/example.d2
Normal file
17
src/diagrams/example.d2
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
|
||||
system: The whole system {
|
||||
componentOne: Component One
|
||||
componentTwo: Component Two {
|
||||
subComponent: Sub Component
|
||||
}
|
||||
}
|
||||
|
||||
externalSystemOne: External System
|
||||
externalSystemOne.shape: cloud
|
||||
|
||||
externalSystemTwo: External System
|
||||
|
||||
|
||||
system.componentOne -> externalSystemTwo
|
||||
externalSystemOne -> system
|
||||
system.componentOne -> system.componentTwo
|
||||
BIN
src/images/01_2_iso-25010-topics-EN.drawio.png
Normal file
BIN
src/images/01_2_iso-25010-topics-EN.drawio.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 81 KiB |
BIN
src/images/05_building_blocks-EN.png
Normal file
BIN
src/images/05_building_blocks-EN.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 275 KiB |
BIN
src/images/08-Crosscutting-Concepts-Structure-EN.png
Normal file
BIN
src/images/08-Crosscutting-Concepts-Structure-EN.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 35 KiB |
45
src/images/STACKIT_Logo_CMYK_Regular_Petrol-MZ.svg
Normal file
45
src/images/STACKIT_Logo_CMYK_Regular_Petrol-MZ.svg
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<svg id="Ebene_1" data-name="Ebene 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 2000 750">
|
||||
<defs>
|
||||
<style>
|
||||
.cls-1 {
|
||||
fill: #004e5a;
|
||||
stroke-width: 0px;
|
||||
}
|
||||
</style>
|
||||
</defs>
|
||||
<g>
|
||||
<polygon class="cls-1" points="846.270303691908339 340.675271609681658 894.595159831504134 340.675271609681658 894.595159831504134 463.112484157354629 917.448071901246294 463.112484157354629 917.448071901246294 340.675271609681658 965.583763218819513 340.675271609681658 965.583763218819513 319.158054600182368 846.270303691908339 319.158054600182368 846.270303691908339 340.675271609681658"/>
|
||||
<polygon class="cls-1" points="1405.155518387644406 319.156928619100654 1378.553089310007636 319.156928619100654 1341.138989869064972 382.679714432586479 1335.497824640970066 391.391993065797578 1341.107462398729695 399.775766717910301 1380.872610341921245 463.111358176272915 1407.862376912264153 463.111358176272915 1361.944868329090241 390.666298257510789 1405.155518387644406 319.156928619100654"/>
|
||||
<rect class="cls-1" x="1484.820932004044153" y="319.158054600182368" width="22.85291206974216" height="143.954429557172261"/>
|
||||
<path class="cls-1" d="M1051.000688209485816,319.158054600182368l-52.831032435566158,143.954429557172261h24.282908045723161l16.459591477901995-46.092598641647783,3.772036629561626-11.319206336673233,17.961650243229087-48.727112881657376c.25221976269313-.698389767010667.52020326055208-1.46856082809245.80169853141706-2.309668697431334.279243308694276.838574411900481.544974844389799,1.606212015543861.797194607082929,2.298971877138683l38.211294048029231,106.149614680271043h24.264892348390276l-52.831032435569796-143.954429557172261h-20.889201060199412Z"/>
|
||||
<path class="cls-1" d="M759.261241449239606,380.083483549420635l-.004503924334131-.001407476353052c-14.811155171730206-6.262706786164927-26.507846666627302-11.209141685769282-26.507846666627302-22.660650799745781,0-8.982232597969414,8.764636753589002-18.273547003343992,23.431666346634302-18.273547003343992,15.196240702269279,0,25.962871822237503,10.017009213661368,26.059706195414037,10.107369195608044l4.425105657966924,4.255927000176598,11.457983505206357-19.546750113455346-2.56273294593484-2.642114612321166c-.574250352561648-.590858573541482-14.335991154512158-14.456471130441059-39.380062412652478-14.456471130441059-26.170052341589326,0-46.667411984752107,17.982762388543051-46.667411984752107,40.93954621323428,0,25.084043586601183,21.654868196950702,34.427716112357302,39.05803182278396,41.934913491000771,15.635373324814282,6.746315661501285,27.985133848116675,12.073895157856896,27.985133848116675,24.917679881520598,0,10.87247334181302-9.007848667617509,18.464963787529996-21.904835997476766,18.464963787529996-18.63949085546119,0-31.525218374488759-13.086433647149533-31.642320407165244-13.206913623078435l-3.884634737911256-4.076333017368597-13.712197634278709,17.729979635307245,2.630291810943163,3.001021082669467c.675588650072314.769045080000069,16.91223587344939,18.832878106550197,46.228279362207104,18.832878106550197,26.802853710491036,0,45.523415203962941-16.912517368720728,45.523415203962941-41.128148044710542,0-27.051414034664049-22.474582425700646-36.554975874270895-40.53306704210263-44.191942572779226ZM758.216331003794039,382.554167541780771h0v-.000281495271338.000281495271338Z"/>
|
||||
<polygon class="cls-1" points="1572.489819161615742 319.158054600182368 1572.489819161615742 340.675271609681658 1620.812423339044472 340.675271609681658 1620.812423339044472 463.112484157354629 1643.667587370953697 463.112484157354629 1643.667587370953697 340.675271609681658 1691.803278688526916 340.675271609681658 1691.803278688526916 319.158054600182368 1572.489819161615742 319.158054600182368"/>
|
||||
<path class="cls-1" d="M1229.043069087081676,338.766733673230192c22.524125593376084,0,36.959203083231841,13.430702363413729,37.101076699746045,13.564412617073685l3.988224997585348,3.839313999302249,12.516405723654316-17.456366232028813-2.684338902949094-2.928958293330652c-1.819585430857842-1.937250454077002-18.727317379976739-18.929993974994431-51.308706010742753-18.929993974994431-39.395826147818298,0-69.340167081139953,29.524068493923551-71.297122204181505,69.295972323616297h-.189164822018938v3.54852938449767c0,.096271382637497.013511773002392.188038840937224.013511773002392.284310223574721,0,.096271382633859-.013511773002392.188038840933586-.013511773002392.284310223571083v3.54852938449767h.189164822018938c1.956955123041553,39.771903829692747,31.901296056363208,69.295690828344959,71.297122204181505,69.295690828344959,32.552113122597802,0,49.484616655550781-16.989928568207688,51.331225632409769-18.953358082475461l2.661819281282078-2.905594185849623-12.518657685821381-17.458899689463578-3.983721073251218,3.841002970926638c-.144125578681269.13483623474167-14.579203068537026,13.565538598159037-37.10332866191311,13.565538598159037-27.694630728583434,0-48.583831788786483-22.010678219321562-48.637878880792414-51.217783038253401.054047092005931-29.205697342578787,20.94324815220898-51.21665705716805,48.637878880792414-51.21665705716805Z"/>
|
||||
</g>
|
||||
<polygon class="cls-1" points="387.797844359825831 260.451144929502334 360.027110854669445 390.58774308343709 429.45576521217663 390.58774308343709 444.398240418478963 320.580146663334745 605.233234801602521 320.580146663334745 618.061486111586419 260.451144929502334 387.797844359825831 260.451144929502334"/>
|
||||
<polygon class="cls-1" points="497.421695939858182 358.123950262208382 482.394935245287343 428.534607435023645 321.021310465963325 428.534607435023645 308.196721311476722 488.663609168856055 538.991676137258764 488.663609168856055 566.85035029741266 358.123950262208382 497.421695939858182 358.123950262208382"/>
|
||||
<g>
|
||||
<path class="cls-1" d="M733.333682718966884,566.859267996314884h-16.956659364394l-4.462642284717731,12.940971966912912h-6.502058955626126l16.192001444727794-45.005298513180605h6.629337499671237l16.192001444731432,45.005298513180605h-6.566191555339174l-4.525788229053433-12.940971966912912ZM724.855353036768065,540.978310717859131s-1.020201663141052,4.079819997197774-1.784859582807258,6.374780411581014l-5.035889060625777,14.278876662487164h13.641497286869708l-4.972743116290076-14.278876662487164c-.764657919666206-2.29496041438324-1.720726983097848-6.374780411581014-1.720726983097848-6.374780411581014h-.12727854404875Z"/>
|
||||
<path class="cls-1" d="M786.553873927830864,534.79494145004719h15.746033212868497c7.586393218483863,0,13.068250510961661,4.207098541242885,13.068250510961661,11.473815416535217,0,4.399496340382029-2.167681870334491,7.905082906290772-5.610122491907532,9.689942489101668v.12727854404875c4.717199372811592,1.403023950668285,7.394982074722066,5.864679580005031,7.394982074722066,10.901555296008155,0,8.478329682198819-6.566191555342812,12.812706767486816-14.4702878062526,12.812706767486816h-16.128855500392092v-45.005298513180605ZM802.299907140699361,553.727871541017521c4.079819997194136,0,6.629337499671237-2.869193845672271,6.629337499671237-6.820748643436673,0-3.952541453145386-2.422238958428352-6.630324155052222-6.756616043719987-6.630324155052222h-9.307120201578073v13.451072798488894h9.434398745626822ZM803.001419116033503,574.31838267074636c4.844477916860342,0,7.71268510714799-3.060604989430431,7.71268510714799-7.650525818196911,0-4.588934173385496-3.059618334045808-7.71268510714799-7.776817706861038-7.71268510714799h-10.071778121247917v15.363210925344902h10.135910720960965Z"/>
|
||||
<path class="cls-1" d="M835.251236873780726,547.544502273201942h5.992944779431127v5.609135836526548c0,1.338891350955237-.128265199426096,2.42223895843199-.128265199426096,2.42223895843199h.128265199426096c1.466169895003986-4.71719937281523,5.227300204383937-8.414197082482133,10.199056665296666-8.414197082482133.828790519379254,0,1.593448439049098.127278544045112,1.593448439049098.127278544045112v6.120223323479877s-.828790519382892-.19141114375816-1.784859582810896-.19141114375816c-3.952541453145386,0-7.585406563102879,2.805061245951947-9.051576458103227,7.585406563099241-.574233431285393,1.848992182527581-.76564457504719,3.825262909100275-.76564457504719,5.801533635672968v13.195529055010411h-6.183369267815578v-32.255737690025853Z"/>
|
||||
<path class="cls-1" d="M885.545008224919002,559.655697065354616h1.403023950668285v-.573246775904408c0-5.291432804100623-2.996472389717383-7.076292386911518-7.076292386911518-7.076292386911518-4.972743116290076,0-8.988430513767526,3.123750933762494-8.988430513767526,3.123750933762494l-2.549517502477102-4.525788229049795s4.653066773094906-3.825262909100275,12.048048847816972-3.825262909100275c8.159639994388272,0,12.749560823154752,4.462642284717731,12.749560823154752,12.622282279106003v20.399099985970679h-5.737401035956282v-3.059618334049446c0-1.466169895000348.12727854404875-2.550504157858086.12727854404875-2.550504157858086h-.12727854404875s-2.613650102193787,6.374780411577376-10.327321864722762,6.374780411577376c-5.545989892198122,0-10.964701240343857-3.378308021859993-10.964701240343857-9.817221033150417,0-10.645024897155963,14.024319574393303-11.091979784392606,19.443030922539037-11.091979784392606ZM878.40556989367542,575.59314142198491c5.227300204387575,0,8.605608226247568-5.482843947858782,8.605608226247568-10.263189265006076v-1.02020166314469h-1.593448439052736c-4.654053428479529,0-13.068250510961661.318689687810547-13.068250510961661,6.119236668098893,0,2.613650102193787,2.040403326285741,5.164154260051873,6.056090723766829,5.164154260051873Z"/>
|
||||
<path class="cls-1" d="M911.932119713423162,547.544502273201942h5.992944779431127v4.270244485574949c0,1.275745406619535-.128265199426096,2.359093014096288-.128265199426096,2.359093014096288h.128265199426096c1.274758751238551-2.805061245955585,5.099035004957841-7.394982074722066,12.111194792156311-7.394982074722066,7.586393218480225,0,11.091979784388968,4.143952596910822,11.091979784388968,12.367725191012141v20.65365707406454h-6.183369267815578v-19.25161977877724c0-4.525788229053433-.956069063431642-8.095507394675224-6.119236668098893-8.095507394675224-4.908610516577028,0-8.861151969722414,3.251029477814882-10.200043320677651,7.904096250913426-.381835632142611,1.274758751238551-.510100831568707,2.740928646238899-.510100831568707,4.335363740668981v15.107667181870056h-6.183369267815578v-32.255737690025853Z"/>
|
||||
<path class="cls-1" d="M972.42396107447712,546.778857698151114c7.458128019054129,0,9.944499577199167,5.100021660338825,9.944499577199167,5.100021660338825h.12727854404875s-.12727854404875-.956069063428004-.12727854404875-2.167681870334491v-14.916256038108259h6.183369267815578v45.005298513180605h-5.864679580005031v-3.059618334049446c0-1.274758751238551.063145944332064-2.167681870334491.063145944332064-2.167681870334491h-.127278544045112s-2.613650102193787,5.991958124053781-10.581878952820261,5.991958124053781c-8.73288677029268,0-14.2157307181551-6.883894587768737-14.2157307181551-16.89252676468459,0-10.263189265009714,6.056090723766829-16.893513420061936,14.598553005678696-16.893513420061936ZM973.252751593860012,575.210319134461315c4.780345317147294,0,9.307120201578073-3.378308021859993,9.307120201578073-11.602080615961313,0-5.737401035956282-2.996472389717383-11.473815416535217-9.115709057816275-11.473815416535217-5.100021660338825,0-9.307120201581711,4.207098541242885-9.307120201581711,11.537948016248265,0,7.01215978719847,3.760143654002604,11.537948016248265,9.115709057819913,11.537948016248265Z"/>
|
||||
<path class="cls-1" d="M1048.785167570928024,546.778857698151114c9.62580988938862,0,17.402627596253296,7.076292386911518,17.402627596253296,16.829380820348888,0,9.817221033150417-7.776817706864676,16.956659364397638-17.402627596253296,16.956659364397638s-17.402627596253296-7.13943833124722-17.402627596253296-16.956659364397638c0-9.75308843343737,7.776817706864676-16.829380820348888,17.402627596253296-16.829380820348888ZM1048.785167570928024,575.210319134461315c6.120223323483515,0,11.091979784392606-4.844477916860342,11.091979784392606-11.602080615961313,0-6.693470099387923-4.971756460909091-11.473815416535217-11.091979784392606-11.473815416535217-6.056090723766829,0-11.091979784388968,4.780345317147294-11.091979784388968,11.473815416535217,0,6.757602699100971,5.035889060622139,11.602080615961313,11.091979784388968,11.602080615961313Z"/>
|
||||
<path class="cls-1" d="M1084.607664460439992,552.962226965966693h-4.016674052862072v-4.971756460909091h4.016674052862072v-1.530302494713396c0-10.645024897152325,8.032361450339522-11.983916248107562,12.112181447533658-11.983916248107562,1.4020372952873,0,2.358106358715304.191411143761798,2.358106358715304.191411143761798v5.290446148719639s-.637379375617456-.12727854404875-1.593448439049098-.12727854404875c-2.359093014096288,0-6.757602699100971.764657919669844-6.757602699100971,6.757602699100971v1.4020372952873h7.649539162815927v4.971756460909091h-7.649539162815927v26.838012997261103h-6.119236668098893v-26.838012997261103Z"/>
|
||||
<path class="cls-1" d="M1141.209123657299642,569.855740386028629s4.780345317147294,4.844477916860342,11.473815416535217,4.844477916860342c4.20808519662387,0,7.777804362245661-2.358106358715304,7.777804362245661-6.629337499671237,0-9.75308843343737-21.802123936638964-7.649539162815927-21.802123936638964-21.482447593447432,0-7.013146442575817,6.056090723766829-12.559136334770301,14.534420405965648-12.559136334770301,8.351051138150069,0,12.749560823151114,4.526774884430779,12.749560823151114,4.526774884430779l-2.868207190287649,5.227300204383937s-4.143952596907184-3.8884088534287-9.881353632863465-3.8884088534287c-4.780345317147294,0-8.159639994388272,2.99548573433276-8.159639994388272,6.565204899958189,0,9.307120201578073,21.802123936635326,6.820748643433035,21.802123936635326,21.419301649111731,0,6.948027187481784-5.354578748432687,12.685428223441704-14.279863317868148,12.685428223441704-9.561677289675572,0-14.916256038108259-5.927825524340733-14.916256038108259-5.927825524340733l3.569719165621791-4.781331972528278Z"/>
|
||||
<path class="cls-1" d="M1199.150460860499152,546.778857698151114c8.095507394671586,0,12.111194792152673,4.71719937281523,12.111194792152673,4.71719937281523l-2.932339790004335,4.335363740668981s-3.442440621573041-3.696997709670541-8.924297914054478-3.696997709670541c-6.502058955626126,0-11.219258328441356,4.84447791686398-11.219258328441356,11.473815416535217,0,6.566191555339174,4.71719937281523,11.602080615961313,11.410669472203153,11.602080615961313,5.991958124053781,0,9.944499577199167-4.334377085287997,9.944499577199167-4.334377085287997l2.486371558145038,4.525788229053433s-4.462642284717731,5.163167604670889-12.876839367199864,5.163167604670889c-10.135910720964603,0-17.276335707589169-7.203570930960268-17.276335707589169-16.89252676468459,0-9.562663945052918,7.140424986624566-16.893513420061936,17.276335707589169-16.893513420061936Z"/>
|
||||
<path class="cls-1" d="M1228.597190683049121,534.79494145004719h6.183369267815578v16.510691132538341c0,1.52931583933605-.12727854404875,2.676796046525851-.12727854404875,2.676796046525851h.12727854404875c1.403023950668285-3.123750933766132,5.482843947858782-7.203570930960268,11.92077030377186-7.203570930960268,7.586393218483863,0,11.091979784388968,4.143952596910822,11.091979784388968,12.367725191012141v20.65365707406454h-6.183369267811941v-19.25161977877724c0-4.525788229053433-.956069063431642-8.095507394675224-6.119236668102531-8.095507394675224-4.845464572241326,0-8.861151969722414,3.314175422146945-10.200043320674013,7.968228850626474-.381835632146249,1.274758751238551-.510100831572345,2.740928646238899-.510100831572345,4.271231140955933v15.107667181870056h-6.183369267815578v-45.005298513180605Z"/>
|
||||
<path class="cls-1" d="M1272.832897999662237,547.544502273201942h6.566191555339174l6.693470099384285,22.629927800637233c.510100831572345,1.657581038762146.764657919669844,3.442440621573041.828790519382892,3.442440621573041h.12727854404875s.318689687810547-1.784859582810896.828790519382892-3.442440621573041l7.012159787194832-22.56678185630517h5.673268436243234l6.949013842862769,22.56678185630517c.510100831572345,1.657581038762146.891936463714956,3.442440621573041.891936463714956,3.442440621573041h.128265199426096s.254557088097499-1.784859582810896.764657919669844-3.442440621573041l6.757602699100971-22.629927800637233h6.502058955622488l-10.39145446443581,32.255737690025853h-6.820748643433035l-6.693470099387923-20.717789673777588c-.510100831572345-1.657581038765784-.891936463714956-3.506573221289727-.891936463714956-3.506573221289727h-.128265199429734s-.381835632142611,1.848992182523943-.891936463714956,3.506573221289727l-6.629337499671237,20.717789673777588h-6.884881243149721l-10.39145446443581-32.255737690025853Z"/>
|
||||
<path class="cls-1" d="M1354.870332898499328,559.655697065354616h1.403023950668285v-.573246775904408c0-5.291432804100623-2.996472389717383-7.076292386911518-7.076292386911518-7.076292386911518-4.972743116290076,0-8.988430513771164,3.123750933762494-8.988430513771164,3.123750933762494l-2.549517502480739-4.525788229049795s4.653066773102182-3.825262909100275,12.04804884782061-3.825262909100275c8.159639994388272,0,12.749560823154752,4.462642284717731,12.749560823154752,12.622282279106003v20.399099985970679h-5.737401035956282v-3.059618334049446c0-1.466169895000348.12727854404875-2.550504157858086.12727854404875-2.550504157858086h-.12727854404875s-2.613650102193787,6.374780411577376-10.327321864722762,6.374780411577376c-5.545989892194484,0-10.964701240343857-3.378308021859993-10.964701240343857-9.817221033150417,0-10.645024897155963,14.024319574393303-11.091979784392606,19.443030922542675-11.091979784392606ZM1347.730894567255746,575.59314142198491c5.227300204383937,0,8.60560822624393-5.482843947858782,8.60560822624393-10.263189265006076v-1.02020166314469h-1.593448439049098c-4.654053428479529,0-13.068250510965299.318689687810547-13.068250510965299,6.119236668098893,0,2.613650102193787,2.040403326289379,5.164154260051873,6.056090723770467,5.164154260051873Z"/>
|
||||
<path class="cls-1" d="M1381.25744438699985,547.544502273201942h5.992944779431127v5.609135836526548c0,1.338891350955237-.128265199426096,2.42223895843199-.128265199426096,2.42223895843199h.128265199426096c1.466169895003986-4.71719937281523,5.227300204387575-8.414197082482133,10.199056665296666-8.414197082482133.828790519382892,0,1.593448439049098.127278544045112,1.593448439049098.127278544045112v6.120223323479877s-.828790519379254-.19141114375816-1.784859582810896-.19141114375816c-3.952541453145386,0-7.585406563102879,2.805061245951947-9.051576458103227,7.585406563099241-.574233431285393,1.848992182527581-.76564457504719,3.825262909100275-.76564457504719,5.801533635672968v13.195529055010411h-6.183369267815578v-32.255737690025853Z"/>
|
||||
<path class="cls-1" d="M1412.363728559073934,576.230520797606005l16.255147389063495-20.399099985970679c1.403023950668285-1.721713638475194,2.677782701906835-2.996472389713745,2.677782701906835-2.996472389713745v-.12727854404875s-1.02020166314469.12727854404875-3.123750933766132.12727854404875h-15.108653837247402v-5.290446148719639h26.583455909163604v3.569719165621791l-16.25613404444448,20.462245930302743c-1.338891350951599,1.657581038762146-2.740928646238899,2.932339790004335-2.740928646238899,2.932339790004335v.128265199426096s1.083347607476753-.128265199426096,3.186896878098196-.128265199426096h16.383412588489591v5.291432804096985h-27.857228005024808v-3.569719165621791Z"/>
|
||||
<path class="cls-1" d="M1484.454690569949889,534.79494145004719h14.916256038111896c13.769762486295804,0,22.821338944399031,8.222785938720335,22.821338944399031,22.438516656875436,0,14.279863317871786-9.051576458103227,22.56678185630517-22.821338944399031,22.56678185630517h-14.916256038111896v-45.005298513180605ZM1498.924978376202489,574.31838267074636c10.135910720960965,0,16.765248220632202-5.992944779431127,16.765248220632202-17.084924563823733,0-11.02784718467592-6.693470099384285-16.956659364394-16.765248220632202-16.956659364394h-8.159639994388272v34.041583928217733h8.159639994388272Z"/>
|
||||
<path class="cls-1" d="M1539.844536959910329,534.79494145004719h6.246515212147642v6.31064781186069h-6.246515212147642v-6.31064781186069ZM1539.907682904242392,547.544502273201942h6.183369267815578v32.255737690025853h-6.183369267815578v-32.255737690025853Z"/>
|
||||
<path class="cls-1" d="M1577.070057800086943,587.832601413567318c5.610122491907532,0,10.200043320674013-2.486371558145038,10.200043320674013-9.052563113480574v-2.358106358718942c0-1.020201663141052.064132599713048-2.040403326285741.064132599713048-2.040403326285741h-.128265199426096c-1.912138126859645,3.187883533475542-4.908610516577028,5.035889060622139-9.561677289675572,5.035889060622139-8.988430513767526,0-14.407141861916898-7.203570930960268-14.407141861916898-16.509704477157356,0-9.243974257246009,5.164154260051873-16.12885550039573,14.088452174106351-16.12885550039573,7.776817706864676,0,10.135910720960965,4.781331972528278,10.135910720960965,4.781331972528278h.12727854404875s-.064132599716686-.445968231855659-.064132599716686-1.020201663141052v-2.995485734336398h5.928812179721717v30.916846339070617c0,10.646011552533309-8.095507394675224,14.725831549731083-16.255147389063495,14.725831549731083-3.889395508813323,0-7.905082906290772-1.083347607480391-11.028833840056905-2.677782701910473l2.040403326285741-4.844477916860342s4.015687397481088,2.167681870334491,8.860165314345068,2.167681870334491ZM1587.397379664809705,562.970859142882546c0-8.414197082485771-4.079819997194136-10.836436040917761-9.115709057816275-10.836436040917761-5.61012249191117,0-8.797019370009366,4.079819997197774-8.797019370009366,10.645024897152325,0,6.693470099387923,3.569719165621791,11.283390928154404,9.371252801291121,11.283390928154404,4.461655629340385,0,8.54147562653452-2.676796046525851,8.54147562653452-11.091979784388968Z"/>
|
||||
<path class="cls-1" d="M1612.636024290739442,534.79494145004719h6.246515212147642v6.31064781186069h-6.246515212147642v-6.31064781186069ZM1612.699170235075144,547.544502273201942h6.183369267811941v32.255737690025853h-6.183369267811941v-32.255737690025853Z"/>
|
||||
<path class="cls-1" d="M1639.47107732186123,552.962226965966693h-4.207098541246523v-4.971756460909091h4.398509685004683v-9.307120201578073h5.991958124053781v9.307120201578073h7.777804362245661v4.971756460909091h-7.777804362245661v14.343995917584834c0,6.43792635590944,4.525788229053433,7.266716875292332,6.884881243149721,7.266716875292332.89292311909594,0,1.466169895000348-.12727854404875,1.466169895000348-.12727854404875v5.481857292481436s-.891936463714956.12727854404875-2.167681870334491.12727854404875c-4.142965941529837,0-12.366738535627519-1.274758751238551-12.366738535627519-12.04804884782061v-15.044521237537992Z"/>
|
||||
<path class="cls-1" d="M1670.894077870983892,571.449188825077727s3.633851765338477,3.761130309383589,9.242987601865025,3.761130309383589c2.677782701906835,0,5.355565403813671-1.4020372952873,5.355565403813671-4.015687397481088,0-5.928812179714441-16.574823732251389-4.717199372811592-16.574823732251389-15.235932381296152,0-5.864679580005031,5.227300204383937-9.179841657532961,11.666213215674361-9.179841657532961,7.075305731534172,0,10.390467809058464,3.569719165625429,10.390467809058464,3.569719165625429l-2.486371558145038,4.654053428479529s-2.868207190287649-2.868207190291287-7.968228850626474-2.868207190291287c-2.677782701906835,0-5.291432804096985,1.146493551812455-5.291432804096985,3.95155479776804,0,5.80153363566933,16.574823732251389,4.526774884430779,16.574823732251389,15.108653837247402,0,5.354578748436325-4.589920828766481,9.370266145917412-11.666213215677999,9.370266145917412-7.904096250909788,0-12.239459991582407-4.71719937281523-12.239459991582407-4.71719937281523l2.996472389717383-4.398509685004683Z"/>
|
||||
</g>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 23 KiB |
BIN
src/images/arc42-logo.png
Normal file
BIN
src/images/arc42-logo.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 8 KiB |
3042
src/images/mmmake_logo_landscape_claim_black.svg
Normal file
3042
src/images/mmmake_logo_landscape_claim_black.svg
Normal file
File diff suppressed because it is too large
Load diff
|
After Width: | Height: | Size: 224 KiB |
BIN
src/themes/fonts/Arial.ttf
Normal file
BIN
src/themes/fonts/Arial.ttf
Normal file
Binary file not shown.
BIN
src/themes/fonts/Arial_Bold.ttf
Normal file
BIN
src/themes/fonts/Arial_Bold.ttf
Normal file
Binary file not shown.
BIN
src/themes/fonts/Arial_Bold_Italic.ttf
Normal file
BIN
src/themes/fonts/Arial_Bold_Italic.ttf
Normal file
Binary file not shown.
BIN
src/themes/fonts/Arial_Italic.ttf
Normal file
BIN
src/themes/fonts/Arial_Italic.ttf
Normal file
Binary file not shown.
BIN
src/themes/fonts/Courier_New.ttf
Normal file
BIN
src/themes/fonts/Courier_New.ttf
Normal file
Binary file not shown.
62
src/themes/mmmake-theme.yml
Normal file
62
src/themes/mmmake-theme.yml
Normal file
|
|
@ -0,0 +1,62 @@
|
|||
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
|
||||
64
src/themes/stackit-theme.yml
Normal file
64
src/themes/stackit-theme.yml
Normal file
|
|
@ -0,0 +1,64 @@
|
|||
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: Courier
|
||||
base:
|
||||
font_family: Arial
|
||||
font_color: #424242
|
||||
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: #004E5A
|
||||
font_size: 17
|
||||
font_style: bold
|
||||
line_height: 1.2
|
||||
margin_bottom: $vertical_rhythm
|
||||
link:
|
||||
font_color: #004E5A
|
||||
font_style: bold
|
||||
# was outline-list which is deprecated (https://docs.asciidoctor.org/pdf-converter/latest/upgrade-to-2/)
|
||||
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: #424242
|
||||
# font_size: 10
|
||||
Loading…
Reference in a new issue