Update AsciiDoc documentation
Change-Id: If87cf07626d1d35e46986fdf6a466f7b7847a4d5
Signed-off-by: Simon Skoczylas <simon.skoczylas@karakun.com>
diff --git a/README.md b/README.md
index 53e285c..9f3b106 100644
--- a/README.md
+++ b/README.md
@@ -15,6 +15,17 @@
Now you can use `gradlew install` in the `org.eclipse.mdm` directory, but you should configure the application first.
+## Generate Documentation
+To generate the current version of documentation the following Gradle tasks can be used
+
+* `:doc:asciidoctor`
+* `:doc:asciidoctorPdf`
+
+For example, you can generate both with
+`./gradlew :doc:asciidoctor :doc:asciidoctorPdf`
+
+The generated files will be located in `doc/build/docs`
+
## Build, deploy and configure the application
1. Edit the `org.eclipse.mdm/nucleus/webclient/src/main/webapp/src/app/core/property.service.ts` and set the `data_host` variable according to your deployment
diff --git a/doc/GettingStarted_mdmbl.pdf b/doc/GettingStarted_mdmbl.pdf
index 29d0131..0bbafaf 100644
--- a/doc/GettingStarted_mdmbl.pdf
+++ b/doc/GettingStarted_mdmbl.pdf
Binary files differ
diff --git a/doc/build.gradle b/doc/build.gradle
index 01323a8..17ca2ee 100644
--- a/doc/build.gradle
+++ b/doc/build.gradle
@@ -5,36 +5,54 @@
}
plugins {
- id 'org.asciidoctor.jvm.convert' version '3.1.0'
- id 'org.asciidoctor.jvm.pdf' version '3.1.0'
+ id 'org.asciidoctor.jvm.convert' version '3.3.2'
+ id 'org.asciidoctor.jvm.pdf' version '3.3.2'
}
repositories {
jcenter()
}
+def mainADoc = 'GettingStarted_mdmblProject'
+def resultPdfName = 'GettingStarted_mdmbl'
+
asciidoctor {
options doctype: 'book'
attributes toclevels: 4, toc: 'left', sectnums: 'numbered'
sourceDir file('src')
sources {
- include 'GettingStarted_mdmblProject.adoc'
+ include "$mainADoc" + ".adoc"
}
- outputDir file('build/docs')
+ outputDir file("$buildDir/docs")
baseDirFollowsSourceDir()
}
+pdfThemes {
+ local 'openMDM', {
+ themeDir = file('themes')
+ themeName = 'openMDM'
+ }
+}
+
asciidoctorPdf {
+ theme 'openMDM'
options doctype: 'book'
- attributes toclevels: 4, toc: 'auto', sectnums: 'numbered'
+ attributes toclevels: 4, toc: 'auto', sectnums: 'numbered', 'chapter-label': ''
sourceDir file('src')
sources {
- include 'GettingStarted_mdmblProject.adoc'
+ include "$mainADoc" + ".adoc"
}
- outputDir file('build/pdf')
+ outputDir file("$buildDir/pdf")
baseDirFollowsSourceDir()
}
+task copyPdf(type: Copy) {
+ from file("$buildDir/pdf/$mainADoc" + ".pdf")
+ into file("$projectDir")
+ rename '.*', "$resultPdfName" + ".pdf"
+}
+
+asciidoctorPdf.finalizedBy(copyPdf)
build.dependsOn(asciidoctorPdf)
build.dependsOn(asciidoctor)
\ No newline at end of file
diff --git a/doc/themes/openMDM-theme.yml b/doc/themes/openMDM-theme.yml
new file mode 100644
index 0000000..54bbdad
--- /dev/null
+++ b/doc/themes/openMDM-theme.yml
@@ -0,0 +1,288 @@
+font:
+ catalog:
+ # Noto Serif supports Latin, Latin-1 Supplement, Latin Extended-A, Greek, Cyrillic, Vietnamese & an assortment of symbols
+ Noto Serif:
+ normal: GEM_FONTS_DIR/notoserif-regular-subset.ttf
+ bold: GEM_FONTS_DIR/notoserif-bold-subset.ttf
+ italic: GEM_FONTS_DIR/notoserif-italic-subset.ttf
+ bold_italic: GEM_FONTS_DIR/notoserif-bold_italic-subset.ttf
+ # M+ 1mn supports ASCII and the circled numbers used for conums
+ M+ 1mn:
+ normal: GEM_FONTS_DIR/mplus1mn-regular-subset.ttf
+ bold: GEM_FONTS_DIR/mplus1mn-bold-subset.ttf
+ italic: GEM_FONTS_DIR/mplus1mn-italic-subset.ttf
+ bold_italic: GEM_FONTS_DIR/mplus1mn-bold_italic-subset.ttf
+page:
+ background_color: FFFFFF
+ layout: portrait
+ initial_zoom: FitH
+ margin: [0.5in, 0.67in, 0.67in, 0.67in]
+ # margin_inner and margin_outer keys are used for recto/verso print margins when media=prepress
+ margin_inner: 0.75in
+ margin_outer: 0.59in
+ size: A4
+base:
+ align: justify
+ # color as hex string (leading # is optional)
+ font_color: 333333
+ # color as RGB array
+ #font_color: [51, 51, 51]
+ # color as CMYK array (approximated)
+ #font_color: [0, 0, 0, 0.92]
+ #font_color: [0, 0, 0, 92%]
+ font_family: Noto Serif
+ # choose one of these font_size/line_height_length combinations
+ #font_size: 14
+ #line_height_length: 20
+ #font_size: 11.25
+ #line_height_length: 18
+ #font_size: 11.2
+ #line_height_length: 16
+ font_size: 10.5
+ #line_height_length: 15
+ # correct line height for Noto Serif metrics
+ line_height_length: 12
+ #font_size: 11.25
+ #line_height_length: 18
+ line_height: $base_line_height_length / $base_font_size
+ font_size_large: round($base_font_size * 1.25)
+ font_size_small: round($base_font_size * 0.85)
+ font_size_min: $base_font_size * 0.75
+ font_style: normal
+ border_color: EEEEEE
+ border_radius: 4
+ border_width: 0.5
+role:
+ line-through:
+ text_decoration: line-through
+ underline:
+ text_decoration: underline
+ big:
+ font_size: $base_font_size_large
+ small:
+ font_size: $base_font_size_small
+ subtitle:
+ font_color: 999999
+ font_size: 0.8em
+ font_style: normal_italic
+# FIXME vertical_rhythm is weird; we should think in terms of ems
+#vertical_rhythm: $base_line_height_length * 2 / 3
+# correct line height for Noto Serif metrics (comes with built-in line height)
+vertical_rhythm: $base_line_height_length
+horizontal_rhythm: $base_line_height_length
+link:
+ font_color: 428BCA
+# literal is currently used for inline monospaced in prose and table cells
+literal:
+ font_color: B12146
+ font_family: M+ 1mn
+button:
+ content: "[\u2009%s\u2009]"
+ font_style: bold
+key:
+ background_color: F5F5F5
+ border_color: CCCCCC
+ border_offset: 2
+ border_radius: 2
+ border_width: 0.5
+ font_family: $literal_font_family
+ separator: "\u202f+\u202f"
+mark:
+ background_color: FFFF00
+ border_offset: 1
+menu:
+ caret_content: " <font size=\"1.15em\" color=\"#B12146\">\u203a</font> "
+ font_style: bold
+heading:
+ align: left
+ font_color: $base_font_color
+ font_style: bold
+ # h1 is used for part titles (book doctype) or the doctitle (article doctype)
+ h1_font_size: floor($base_font_size * 2.6)
+ # h2 is used for chapter titles (book doctype only)
+ h2_font_size: floor($base_font_size * 2.15)
+ h3_font_size: round($base_font_size * 1.7)
+ h4_font_size: $base_font_size_large
+ h5_font_size: $base_font_size
+ h6_font_size: $base_font_size_small
+ #line_height: 1.4
+ # correct line height for Noto Serif metrics (comes with built-in line height)
+ line_height: 1
+ margin_top: $vertical_rhythm * 0.4
+ margin_bottom: $vertical_rhythm * 0.9
+ min_height_after: $base_line_height_length * 1.5
+title_page:
+ align: right
+ logo:
+ top: 10%
+ title:
+ top: 55%
+ font_size: $heading_h1_font_size
+ font_color: $role_subtitle_font_color
+ line_height: 0.9
+ subtitle:
+ font_size: $heading_h3_font_size
+ font_style: bold_italic
+ line_height: 1
+ authors:
+ margin_top: $base_font_size * 1.25
+ font_size: $base_font_size_large
+ font_color: 181818
+ revision:
+ margin_top: $base_font_size * 1.25
+block:
+ margin_bottom: $vertical_rhythm
+caption:
+ align: left
+ font_size: $base_font_size * 0.95
+ font_style: italic
+ # FIXME perhaps set line_height instead of / in addition to margins?
+ margin_inside: $vertical_rhythm / 3
+ margin_outside: 0
+lead:
+ font_size: $base_font_size_large
+ line_height: 1.4
+abstract:
+ font_color: 5C6266
+ font_size: $lead_font_size
+ line_height: $lead_line_height
+ font_style: italic
+ first_line_font_style: bold
+ title:
+ align: center
+ font_color: $heading_font_color
+ font_size: $heading_h4_font_size
+ font_style: $heading_font_style
+admonition:
+ column_rule_color: $base_border_color
+ column_rule_width: $base_border_width
+ padding: [0, $horizontal_rhythm, 0, $horizontal_rhythm]
+ #icon:
+ # tip:
+ # name: far-lightbulb
+ # stroke_color: 111111
+ # size: 24
+ label:
+ text_transform: uppercase
+ font_style: bold
+blockquote:
+ font_size: $base_font_size_large
+ border_color: $base_border_color
+ border_width: 0
+ border_left_width: 5
+ # FIXME disable negative padding bottom once margin collapsing is implemented
+ padding: [0, $horizontal_rhythm, $block_margin_bottom * -0.75, $horizontal_rhythm + $blockquote_border_left_width / 2]
+ cite:
+ font_size: $base_font_size_small
+ font_color: $role_subtitle_font_color
+verse:
+ font_size: $blockquote_font_size
+ border_color: $blockquote_border_color
+ border_width: $blockquote_border_width
+ border_left_width: $blockquote_border_left_width
+ padding: $blockquote_padding
+ cite:
+ font_size: $blockquote_cite_font_size
+ font_color: $blockquote_cite_font_color
+# code is used for source blocks (perhaps change to source or listing?)
+code:
+ font_color: $base_font_color
+ font_family: $literal_font_family
+ font_size: ceil($base_font_size)
+ padding: $code_font_size
+ line_height: 1.25
+ # line_gap is an experimental property to control how a background color is applied to an inline block element
+ line_gap: 3.8
+ background_color: F5F5F5
+ border_color: CCCCCC
+ border_radius: $base_border_radius
+ border_width: 0.75
+conum:
+ font_family: $literal_font_family
+ font_color: $literal_font_color
+ font_size: $base_font_size
+ line_height: 4 / 3
+ glyphs: circled
+example:
+ border_color: $base_border_color
+ border_radius: $base_border_radius
+ border_width: 0.75
+ background_color: $page_background_color
+ # FIXME reenable padding bottom once margin collapsing is implemented
+ padding: [$vertical_rhythm, $horizontal_rhythm, 0, $horizontal_rhythm]
+image:
+ align: left
+prose:
+ margin_bottom: $block_margin_bottom
+sidebar:
+ background_color: EEEEEE
+ border_color: E1E1E1
+ border_radius: $base_border_radius
+ border_width: $base_border_width
+ # FIXME reenable padding bottom once margin collapsing is implemented
+ padding: [$vertical_rhythm, $vertical_rhythm * 1.25, 0, $vertical_rhythm * 1.25]
+ title:
+ align: center
+ font_color: $heading_font_color
+ font_size: $heading_h4_font_size
+ font_style: $heading_font_style
+thematic_break:
+ border_color: $base_border_color
+ border_style: solid
+ border_width: $base_border_width
+ margin_top: $vertical_rhythm * 0.5
+ margin_bottom: $vertical_rhythm * 1.5
+description_list:
+ term_font_style: bold
+ term_spacing: $vertical_rhythm / 4
+ description_indent: $horizontal_rhythm * 1.25
+outline_list:
+ indent: $horizontal_rhythm * 1.5
+ #marker_font_color: 404040
+ # NOTE outline_list_item_spacing applies to list items that do not have complex content
+ item_spacing: $vertical_rhythm / 2
+table:
+ background_color: $page_background_color
+ border_color: DDDDDD
+ border_width: $base_border_width
+ cell_padding: 3
+ head:
+ font_style: bold
+ border_bottom_width: $base_border_width * 2.5
+ body:
+ stripe_background_color: F9F9F9
+ foot:
+ background_color: F0F0F0
+toc:
+ indent: $horizontal_rhythm
+ line_height: 1.4
+ dot_leader:
+ #content: ". "
+ font_color: A9A9A9
+ #levels: 2 3
+footnotes:
+ font_size: round($base_font_size * 0.75)
+ item_spacing: $outline_list_item_spacing / 2
+header:
+ font_size: $base_font_size_small
+ line_height: 1
+ vertical_align: middle
+footer:
+ font_size: $base_font_size_small
+ # NOTE if background_color is set, background and border will span width of page
+ border_color: DDDDDD
+ border_width: 0.25
+ height: $base_line_height_length * 2.5
+ line_height: 1
+ padding: [$base_line_height_length / 2, 1, 0, 1]
+ vertical_align: top
+ recto:
+ left:
+ content: 'Copyright(c) 2017-2021, A. Wittek and others. Made available under the Eclipse Public License 2.0'
+ right:
+ content: '{page-number}'
+ verso:
+ left:
+ content: 'Copyright(c) 2017-2021, A. Wittek and others. Made available under the Eclipse Public License 2.0'
+ right:
+ content: '{page-number}'
\ No newline at end of file
