giblish 0.8.2 → 1.0.0.rc2

data/docs/concepts/text_search_im/search_request.svg

@@ -0,0 +1,408 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentScriptType="application/ecmascript" contentStyleType="text/css" height="733.3333px" preserveAspectRatio="none" style="width:823px;height:733px;background:#00000000;" version="1.1" viewBox="0 0 823 733" width="823.9583px" zoomAndPan="magnify"><defs/><g><rect height="45.0846" rx="4.1667" ry="4.1667" style="stroke:#BABDBF;stroke-width:1.0416666666666667;fill:none;" width="519.7917" x="165.1042" y="14.5833"/><text fill="#2FA4E7" font-family="Verdana" font-size="20.8333" lengthAdjust="spacing" textLength="492.7083" x="178.6458" y="44.338">Using a Passenger web-app for search requests</text><rect fill="#EEEEEE" height="649.2188" rx="4.1667" ry="4.1667" style="stroke:#868E96;stroke-width:1.0416666666666667;" width="695.8333" x="112.5" y="71.1263"/><text fill="#343A40" font-family="Verdana" font-size="12.5" font-weight="bold" lengthAdjust="spacing" textLength="187.5" x="366.6667" y="87.9374">Document-hosting Server</text><line style="stroke:#BABDBF;stroke-width:2.0833333333333335;stroke-dasharray:5.0,5.0;" x1="34.375" x2="34.375" y1="173.1445" y2="726.5951"/><line style="stroke:#BABDBF;stroke-width:2.0833333333333335;stroke-dasharray:5.0,5.0;" x1="207.2917" x2="207.2917" y1="173.1445" y2="726.5951"/><line style="stroke:#BABDBF;stroke-width:2.0833333333333335;stroke-dasharray:5.0,5.0;" x1="397.9167" x2="397.9167" y1="173.1445" y2="726.5951"/><line style="stroke:#BABDBF;stroke-width:2.0833333333333335;stroke-dasharray:5.0,5.0;" x1="594.7917" x2="594.7917" y1="173.1445" y2="726.5951"/><line style="stroke:#BABDBF;stroke-width:2.0833333333333335;stroke-dasharray:5.0,5.0;" x1="753.125" x2="753.125" y1="173.1445" y2="726.5951"/><text fill="#2FA4E7" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="42.7083" x="10.4167" y="164.9882">Viewer</text><ellipse cx="34.8958" cy="92.9688" rx="8.3333" ry="8.3333" style="stroke:#2FA4E7;stroke-width:2.0833333333333335;fill:none;"/><path d="M34.8958,101.3021 L34.8958,129.4271 M21.3542,109.6354 L48.4375,109.6354 M34.8958,129.4271 L21.3542,145.0521 M34.8958,129.4271 L48.4375,145.0521 " fill="none" style="stroke:#2FA4E7;stroke-width:2.0833333333333335;"/><rect height="39.5508" rx="4.1667" ry="4.1667" style="stroke:#2FA4E7;stroke-width:1.5625;fill:none;" width="98.9583" x="158.3333" y="132.5521"/><text fill="#2FA4E7" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="73.9583" x="170.8333" y="156.6549">Web Server</text><rect height="39.5508" rx="4.1667" ry="4.1667" style="stroke:#2FA4E7;stroke-width:1.5625;fill:none;" width="94.7917" x="351.0417" y="132.5521"/><text fill="#2FA4E7" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="69.7917" x="363.5417" y="156.6549">Passenger</text><rect height="54.1016" rx="4.1667" ry="4.1667" style="stroke:#2FA4E7;stroke-width:1.5625;fill:none;" width="111.4583" x="539.5833" y="118.0013"/><text fill="#2FA4E7" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="86.4583" x="552.0833" y="142.1041">Search script</text><text fill="#2FA4E7" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="67.7083" x="561.4583" y="156.6549">(Web app)</text><text fill="#2FA4E7" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="84.375" x="708.3333" y="164.9882">Search index</text><path d="M734.8958,110.6771 C734.8958,100.2604 753.6458,100.2604 753.6458,100.2604 C753.6458,100.2604 772.3958,100.2604 772.3958,110.6771 L772.3958,137.7604 C772.3958,148.1771 753.6458,148.1771 753.6458,148.1771 C753.6458,148.1771 734.8958,148.1771 734.8958,137.7604 L734.8958,110.6771 " style="stroke:#2FA4E7;stroke-width:1.5625;fill:none;"/><path d="M734.8958,110.6771 C734.8958,121.0938 753.6458,121.0938 753.6458,121.0938 C753.6458,121.0938 772.3958,121.0938 772.3958,110.6771 " fill="none" style="stroke:#2FA4E7;stroke-width:1.5625;"/><path d="M493.75,192.9362 L493.75,277.3112 A4.1667,4.1667 0 0 0 497.9167,281.4779 L692.7083,281.4779 A4.1667,4.1667 0 0 0 696.875,277.3112 L696.875,199.1862 L686.4583,188.7695 L497.9167,188.7695 A4.1667,4.1667 0 0 0 493.75,192.9362 " style="stroke:#033C73;stroke-width:1.0416666666666667;fill:none;"/><path d="M686.4583,188.7695 L686.4583,197.1029 A2.0833,2.0833 0 0 0 688.5417,199.1862 L696.875,199.1862 L686.4583,188.7695 " style="stroke:#033C73;stroke-width:1.0416666666666667;fill:none;"/><text fill="#033C73" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="119.7917" x="505.2083" y="210.789">This could eg be a</text><text fill="#033C73" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="166.6667" x="505.2083" y="225.3398">sinatra-based application</text><text fill="#033C73" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="81.25" x="505.2083" y="239.8905">that use the</text><text fill="#033C73" font-family="monospace" font-size="12.5" lengthAdjust="spacing" textLength="167.7083" x="505.2083" y="254.4413">Giblish::RequestManager</text><text fill="#033C73" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="37.5" x="505.2083" y="268.9921">class.</text><polygon fill="#2FA4E7" points="195.3125,329.1667,205.7292,333.3333,195.3125,337.5,199.4792,333.3333" style="stroke:#2FA4E7;stroke-width:1.0416666666666667;"/><line style="stroke:#2FA4E7;stroke-width:3.125;" x1="34.8958" x2="201.5625" y1="333.3333" y2="333.3333"/><text fill="#343A40" font-family="Verdana" font-size="12.5" font-weight="bold" lengthAdjust="spacing" textLength="8.3333" x="47.3958" y="315.8183">1</text><text fill="#343A40" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="87.5" x="70.3125" y="308.5429">Search Query</text><text fill="#343A40" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="76.0417" x="70.3125" y="323.0937">(html POST)</text><polygon fill="#2FA4E7" points="385.9375,383.2682,396.3542,387.4349,385.9375,391.6016,390.1042,387.4349" style="stroke:#2FA4E7;stroke-width:1.0416666666666667;"/><line style="stroke:#2FA4E7;stroke-width:3.125;" x1="207.8125" x2="392.1875" y1="387.4349" y2="387.4349"/><text fill="#343A40" font-family="Verdana" font-size="12.5" font-weight="bold" lengthAdjust="spacing" textLength="8.3333" x="220.3125" y="369.9198">2</text><text fill="#343A40" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="65.625" x="243.2292" y="362.6444">hand over</text><text fill="#343A40" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="88.5417" x="243.2292" y="377.1952">POST request</text><polygon fill="#2FA4E7" points="582.8125,437.3698,593.2292,441.5365,582.8125,445.7031,586.9792,441.5365" style="stroke:#2FA4E7;stroke-width:1.0416666666666667;"/><line style="stroke:#2FA4E7;stroke-width:3.125;" x1="398.4375" x2="589.0625" y1="441.5365" y2="441.5365"/><text fill="#343A40" font-family="Verdana" font-size="12.5" font-weight="bold" lengthAdjust="spacing" textLength="8.3333" x="410.9375" y="424.0214">3</text><text fill="#343A40" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="65.625" x="433.8542" y="416.746">hand over</text><text fill="#343A40" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="88.5417" x="433.8542" y="431.2968">POST request</text><polygon fill="#2FA4E7" points="741.1458,491.4714,751.5625,495.638,741.1458,499.8047,745.3125,495.638" style="stroke:#2FA4E7;stroke-width:1.0416666666666667;"/><line style="stroke:#2FA4E7;stroke-width:3.125;" x1="595.3125" x2="747.3958" y1="495.638" y2="495.638"/><text fill="#343A40" font-family="Verdana" font-size="12.5" font-weight="bold" lengthAdjust="spacing" textLength="8.3333" x="607.8125" y="478.123">4</text><text fill="#343A40" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="71.875" x="630.7292" y="470.8476">Search the</text><text fill="#343A40" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="34.375" x="630.7292" y="485.3984">index</text><polygon fill="#2FA4E7" points="409.8958,570.5241,399.4792,574.6908,409.8958,578.8574,405.7292,574.6908" style="stroke:#2FA4E7;stroke-width:1.0416666666666667;"/><line style="stroke:#2FA4E7;stroke-width:3.125;" x1="403.6458" x2="594.2708" y1="574.6908" y2="574.6908"/><text fill="#343A40" font-family="Verdana" font-size="12.5" font-weight="bold" lengthAdjust="spacing" textLength="8.3333" x="421.3542" y="557.1757">5</text><text fill="#343A40" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="92.7083" x="444.2708" y="549.9003">Return search</text><text fill="#343A40" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="80.2083" x="444.2708" y="564.4511">result (html)</text><path d="M600,513.3464 L600,597.7214 A4.1667,4.1667 0 0 0 604.1667,601.888 L812.5,601.888 A4.1667,4.1667 0 0 0 816.6667,597.7214 L816.6667,519.5964 L806.25,509.1797 L604.1667,509.1797 A4.1667,4.1667 0 0 0 600,513.3464 " style="stroke:#033C73;stroke-width:1.0416666666666667;fill:none;"/><path d="M806.25,509.1797 L806.25,517.513 A2.0833,2.0833 0 0 0 808.3333,519.5964 L816.6667,519.5964 L806.25,509.1797 " style="stroke:#033C73;stroke-width:1.0416666666666667;fill:none;"/><text fill="#033C73" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="135.4167" x="611.4583" y="531.1991">Giblish contains help</text><text fill="#033C73" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="136.4583" x="611.4583" y="545.7499">classes fthat provide</text><text fill="#033C73" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="156.25" x="611.4583" y="560.3007">most of the heavy lifting</text><text fill="#033C73" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="184.375" x="611.4583" y="574.8515">for retrieving and formatting</text><text fill="#033C73" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="116.6667" x="611.4583" y="589.4023">the search result.</text><polygon fill="#2FA4E7" points="219.2708,649.5768,208.8542,653.7435,219.2708,657.9102,215.1042,653.7435" style="stroke:#2FA4E7;stroke-width:1.0416666666666667;"/><line style="stroke:#2FA4E7;stroke-width:3.125;" x1="213.0208" x2="397.3958" y1="653.7435" y2="653.7435"/><text fill="#343A40" font-family="Verdana" font-size="12.5" font-weight="bold" lengthAdjust="spacing" textLength="8.3333" x="230.7292" y="636.2284">6</text><text fill="#343A40" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="92.7083" x="253.6458" y="628.953">Return search</text><text fill="#343A40" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="80.2083" x="253.6458" y="643.5038">result (html)</text><polygon fill="#2FA4E7" points="46.3542,703.6784,35.9375,707.8451,46.3542,712.0117,42.1875,707.8451" style="stroke:#2FA4E7;stroke-width:1.0416666666666667;"/><line style="stroke:#2FA4E7;stroke-width:3.125;" x1="40.1042" x2="206.7708" y1="707.8451" y2="707.8451"/><text fill="#343A40" font-family="Verdana" font-size="12.5" font-weight="bold" lengthAdjust="spacing" textLength="8.3333" x="57.8125" y="690.33">7</text><text fill="#343A40" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="92.7083" x="80.7292" y="683.0546">Return search</text><text fill="#343A40" font-family="Verdana" font-size="12.5" lengthAdjust="spacing" textLength="80.2083" x="80.7292" y="697.6054">result (html)</text><!--MD5=[13204aa85ad97e6fa7eec39605455a40]
+@startuml
+!theme cerulean-outline
+hide footbox
+autonumber
+
+title "Using a Passenger web-app for search requests"
+
+actor       Viewer       as Vi
+
+box "Document-hosting Server" #EEEEEE
+participant "Web Server" as Webserv
+participant "Passenger"   as Pass
+participant "Search script\n(Web app)"   as Searcher
+note over of Searcher
+  This could eg be a
+  sinatra-based application 
+  that use the 
+  ""Giblish::RequestManager""
+  class.
+end note
+database "Search index"   as Index
+end box
+
+Vi -> Webserv     : Search Query\n(html POST)
+Webserv -> Pass : hand over\nPOST request
+Pass -> Searcher : hand over\nPOST request
+Searcher -> Index : Search the\nindex
+Searcher -> Pass : Return search\nresult (html)
+note right
+  Giblish contains help 
+  classes fthat provide 
+  most of the heavy lifting 
+  for retrieving and formatting
+  the search result.
+end note
+Pass -> Webserv : Return search\nresult (html)
+Webserv -> Vi  : Return search\nresult (html)
+@enduml
+
+@startuml
+
+
+
+skinparam backgroundColor transparent
+skinparam useBetaStyle false
+
+
+
+
+
+
+
+skinparam defaultFontName       "Verdana"
+skinparam defaultFontSize       12
+skinparam dpi                   100
+skinparam shadowing             false
+skinparam roundcorner           8
+skinparam ParticipantPadding    40
+skinparam BoxPadding            40
+skinparam Padding               5
+skinparam ArrowColor            #868E96
+skinparam stereotype {
+    CBackgroundColor #EDF0F2
+    CBorderColor #BABDBF
+    ABackgroundColor #8FB961
+    ABorderColor $SUCCESS_DARK
+    IBackgroundColor #D2494E
+    IBorderColor $DANGER_DARK
+    EBackgroundColor #E47833
+    EBorderColor $WARNING_DARK
+    NBackgroundColor #35638F
+    NBorderColor $INFO_DARK
+}
+skinparam title {
+	FontColor	                 #2FA4E7
+	BorderColor	                 #BABDBF
+	FontSize	    	         20
+	BorderRoundCorner            8
+	BorderThickness 	         1
+	BackgroundColor              transparent
+}
+
+skinparam legend {
+	BackgroundColor transparent
+	BorderColor #BABDBF
+	FontColor #343A40
+}
+
+skinparam swimlane {
+	BorderColor #033C73
+	BorderThickness 2
+	TitleBackgroundColor  #EDF0F2-#E9ECEF
+	TitleFontColor #2FA4E7
+}
+
+
+skinparam activity {
+		FontColor #2FA4E7
+	BorderColor #2FA4E7
+	BackgroundColor transparent
+	BarColor #73A839
+	StartColor #033C73
+	EndColor #033C73
+	DiamondBackgroundColor transparent
+  	DiamondBorderColor #BABDBF
+	DiamondFontColor #BABDBF
+}
+
+
+skinparam participant {
+		FontColor #2FA4E7
+	BorderColor #2FA4E7
+	BackgroundColor transparent
+	ParticipantBorderThickness 2
+}
+
+
+skinparam actor {
+		FontColor #2FA4E7
+	BorderColor #2FA4E7
+	BackgroundColor transparent
+}
+
+
+skinparam arrow {
+	Thickness 3
+	Color #2FA4E7
+	FontColor #343A40
+}
+
+
+skinparam sequence {
+	BorderColor #2FA4E7
+	TitleFontColor #2FA4E7
+	BackgroundColor transparent
+	StartColor #2FA4E7
+	EndColor #2FA4E7
+	BoxBackgroundColor transparent
+	BoxBorderColor #868E96
+	BoxFontColor #343A40
+	LifeLineBorderColor #BABDBF
+	LifeLineBorderThickness 2
+	LifeLineBackgroundColor transparent
+	GroupBorderColor #868E96
+	GroupFontColor #343A40
+	GroupHeaderFontColor #033C73
+	DividerBackgroundColor transparent
+    DividerBorderColor #868E96
+    DividerBorderThickness 2
+    DividerFontColor #343A40
+	ReferenceBackgroundColor transparent
+	ReferenceBorderColor #868E96
+	ReferenceFontColor #343A40
+	ReferenceHeaderFontColor #033C73
+}
+
+
+skinparam partition {
+	BorderColor #2FA4E7
+	FontColor #2FA4E7
+	BackgroundColor transparent
+}
+
+
+skinparam collections {
+		FontColor #2FA4E7
+	BorderColor #2FA4E7
+	BackgroundColor transparent
+}
+
+
+skinparam control {
+		FontColor #2FA4E7
+	BorderColor #2FA4E7
+	BackgroundColor transparent
+}
+
+
+skinparam entity {
+		FontColor #2FA4E7
+	BorderColor #2FA4E7
+	BackgroundColor transparent
+}
+
+
+skinparam boundary {
+		FontColor #2FA4E7
+	BorderColor #2FA4E7
+	BackgroundColor transparent
+}
+
+
+skinparam agent {
+	BackgroundColor transparent
+	BorderColor #999999
+	FontColor #333333
+}
+
+
+skinparam note {
+	BorderThickness 1
+	BackgroundColor transparent
+	BorderColor #033C73
+	FontColor #033C73
+}
+
+
+skinparam artifact {
+	BackgroundColor transparent
+	BorderColor #868E96
+	FontColor #868E96
+}
+
+
+skinparam component {
+		FontColor #2FA4E7
+	BorderColor #2FA4E7
+	BackgroundColor transparent
+}
+
+
+skinparam interface {
+	BackgroundColor  transparent
+	BorderColor  #C71C22
+	FontColor #343A40
+}
+
+
+skinparam storage {
+	BackgroundColor transparent
+  	BorderColor #DD5600
+	FontColor #DD5600
+}
+
+
+skinparam node {
+	BackgroundColor transparent
+	BorderColor #343A40
+	FontColor #343A40
+}
+
+
+skinparam cloud {
+	BackgroundColor #F2FCFE-#eeeeee
+	BorderColor #F2FCFE
+	FontColor #343A40
+}
+
+
+skinparam database {
+		FontColor #2FA4E7
+	BorderColor #2FA4E7
+	BackgroundColor transparent
+}
+
+
+skinparam class {
+		FontColor #2FA4E7
+	BorderColor #2FA4E7
+	BackgroundColor transparent
+	FontColor #F8F9FA
+	HeaderBackgroundColor #2FA4E7-#2683B9
+	StereotypeFontColor #343A40
+	BorderThickness 1
+	AttributeFontColor #343A40
+	AttributeFontSize 11
+}
+
+
+skinparam object {
+		FontColor #2FA4E7
+	BorderColor #2FA4E7
+	BackgroundColor transparent
+	StereotypeFontColor #343A40
+	BorderThickness 1
+	AttributeFontColor #BABDBF
+	AttributeFontSize 11
+}
+
+
+skinparam usecase {
+		FontColor #2FA4E7
+	BorderColor #2FA4E7
+	BackgroundColor transparent
+	BorderThickness 2
+	StereotypeFontColor #2FA4E7
+}
+
+
+skinparam rectangle {
+		FontColor #2FA4E7
+	BorderColor #2FA4E7
+	BackgroundColor transparent
+	BorderThickness 2
+	StereotypeFontColor #2FA4E7
+}
+
+
+skinparam package {
+	BackgroundColor transparent
+  	BorderColor #2FA4E7
+	FontColor #2FA4E7
+	BorderThickness 2
+}
+
+
+skinparam folder {
+	BackgroundColor transparent
+  	BorderColor #DD5600
+	FontColor #DD5600
+	BorderThickness 2
+}
+
+
+skinparam frame {
+	BackgroundColor transparent
+  	BorderColor #033C73
+	FontColor #033C73
+	BorderThickness 2
+}
+
+
+skinparam state {
+		FontColor #2FA4E7
+	BorderColor #2FA4E7
+	BackgroundColor transparent
+	StartColor #033C73
+	EndColor #033C73
+	AttributeFontColor #BABDBF
+	AttributeFontSize 11
+}
+
+
+skinparam queue {
+		FontColor #2FA4E7
+	BorderColor #2FA4E7
+	BackgroundColor transparent
+}
+
+
+skinparam card {
+	BackgroundColor transparent
+	BorderColor #033C73
+	FontColor #033C73
+}
+
+
+skinparam file {
+	BackgroundColor transparent
+	BorderColor #868E96
+	FontColor #868E96
+}
+
+
+skinparam stack {
+		FontColor #2FA4E7
+	BorderColor #2FA4E7
+	BackgroundColor transparent
+}
+
+
+
+hide footbox
+autonumber
+
+title "Using a Passenger web-app for search requests"
+
+actor       Viewer       as Vi
+
+box "Document-hosting Server" #EEEEEE
+participant "Web Server" as Webserv
+participant "Passenger"   as Pass
+participant "Search script\n(Web app)"   as Searcher
+note over of Searcher
+  This could eg be a
+  sinatra-based application 
+  that use the 
+  ""Giblish::RequestManager""
+  class.
+end note
+database "Search index"   as Index
+end box
+
+Vi -> Webserv     : Search Query\n(html POST)
+Webserv -> Pass : hand over\nPOST request
+Pass -> Searcher : hand over\nPOST request
+Searcher -> Index : Search the\nindex
+Searcher -> Pass : Return search\nresult (html)
+note right
+  Giblish contains help 
+  classes fthat provide 
+  most of the heavy lifting 
+  for retrieving and formatting
+  the search result.
+end note
+Pass -> Webserv : Return search\nresult (html)
+Webserv -> Vi  : Return search\nresult (html)
+@enduml
+
+PlantUML version 1.2021.7(Sun May 23 14:40:07 CEST 2021)
+(GPL source distribution)
+Java Runtime: OpenJDK Runtime Environment
+JVM: OpenJDK 64-Bit Server VM
+Default Encoding: UTF-8
+Language: en
+Country: US
+--></g></svg>

data/docs/howtos/trigger_generation.adoc

@@ -0,0 +1,180 @@
+= Trigger document generation
+:imagesdir: trigger_generation_im
+:numbered:
+:docid: G-003
+:toc: left
+
+== Purpose
+
+To describe how to use `giblish` as a tool for creating a static web site backed by a git repo that is automatically generated each time a contributor push changes to the git repo.
+
+This text covers the followwing deployment scenarios:app-name: 
+
+ . Using a git hook together with a simple (well) shell script
+ . Using a git hook together with Jenkins.
+
+They have been tested on Linux servers (Ubuntu). Most of the tools and scripts should work on a Windows server as well but might need some tweaking and is, again, not tested.
+
+If you want to dive straight in and setup one of the scenarios below, jump to <<setup_instructions>>, otherwise read on for some examples and considerations.
+
+== Git hook and shell script
+
+This requires the least number of dependencies to work but is more limited.
+
+.Deploy using git hook and shell script
+image::deploy_with_hooks.svg[]
+
+The components needed on the server are:
+
+A 'Main Repo'::
+The common (bare) git repo used by all content writers to push updates to. This repo shall be setup with a server-side hook (_post-receive_) that initiates the html generation and is triggered by each push to the repo.
+
+A 'Staging Repo'::
+A mirror of the _Main Repo_ that fulfills two functions:
+
+ . to provide a checked-out working tree with the source files (adoc files).
+ . to provide a script that uses giblish to generate html documents and publish those docs to a location where a web server can access them.
+
+Web Server::
+Apache, Ngnix or other web server that provides clients with HTML pages located somewhere on the file system on the server (e.g under /var/www/... )
+
+=== Pros & Cons
+
+Pros::
+ * it has few dependencies on external tools, only git, giblish and a web server are needed for this to work.
+ * giblish provides templates for the `post-receive` hook.
+
+Cons::
+ * The hook and publish scripts provided with giblish runs synchronously at each push from a _Doc Writer_ to the _Main Repo_. The time it takes to generate the HTML docs from the adoc source will thus be added to each push to the _Main Repo_.
+ * You need to manually setup the _Staging Repo_ on the server and this is a bit more 'hackish' than letting a build orchestrator tool implement a proper 'build' of your documents. You might for example end up with race conditions if two pushes to the _Main Repo_ are done close in time.
+
+=== Using a combination of Jenkins and git hook
+
+This setup adds a Jenkins (or similar build orchestrator) installation so it is more tools to setup but offer more flexibility and performance. It is also more robust and thus more 'production friendly'.
+
+If you are already doing some kind of development, chances are that you already have this kind of setup as a CI pipeline.
+
+.Deploy using Jenkins
+image::deploy_with_jenkins.svg[]
+
+The components needed on the server are:
+
+Main Repo::
+The common (bare) git repo used by all content writers to push updates to. This repo needs to be setup with a server-side hook (_post-receive_) that are executed by git after each push to the repository.
+
+Jenkins instance::
+A running instance of Jenkins and one or more defined build jobs that use giblish to build the HTML documents.
+
+Web Server::
+Apache, Ngnix or other web server that provides clients with HTML pages located somewhere on the file system on the server (e.g under /var/www/... )
+
+==== Pros & cons
+
+Pros::
+ * Using Jenkins enables a lot of flexibility and scaleability. You can setup multiple Jenkins agents to increase performance, you can define many build jobs where each job builds either a particular branch from a particular git repo or many branches from one or many repos.
+
+Cons::
+ * You need to be familiar with, and maintain, the Jenkins instance.
+
+[[setup_instructions]]
+== Setup instructions
+
+Follow the instructions below to get one of the above setups running on your server.
+
+=== Some preliminary notes
+
+IMPORTANT: Setting up permissions and secure your setup from unwanted access is outside the scope of these instructions. You must understand and implement the proper user/groups/rules for your use case.
+
+NOTE: git server side hooks are used in the instructions below. For details on git hooks see https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks[this doc].
+
+[[common_setup]]
+=== Initial setup
+
+These steps are common to both deployment scenarios.
+
+giblish setup::
+ . Install ruby on the _Server_ (a version no more than 18 months old)
+ . Install giblish on the _Server_ using `gem install giblish`
+
+git and gitrepo setup::
+ . Install git on the _Server_.
+ . Setup the *bare* _Main Repo_ on the _Server_ by either.
+ .. Copy a bare repo you already use to the _Server_ file system.
+ .. Initiate a new repo using `git init --bare <your_repo_name>` somewhere on the _Server_ file system.
++
+NOTE: If you start with an empty, bare, _Main Repo_ on the _Server_, it is a good idea to directly clone it to your local machine, commit some content to the 'master' branch and push the result back to the _Main Repo_. An empty, bare repo does not even contain a 'master' branch from the start and this can lead to some edge cases that complicate things.
+
+=== Use a git hook and shell script
+
+First, follow the steps described in <<common_setup>>. Then proceed with the steps below.
+
+ . Setup the _Staging Repo_ on the _Server_ by cloning the _Main Repo_ to a suitable folder in the _Server_ file system, ex:
++
+.Setup a staging repo in your home folder on the _Server_
+====
+[source, bash]
+----
+# go to your home directory
+cd ~ 
+
+# clone the Main Repo, assuming it is located at /usr/local/main_repo.git
+git clone file:///usr/local/main_repo.git
+----
+====
+ . Make a copy of the `post-receive.example` template from the installed `giblish` gem.
++
+.Find the `post-receive` template in the giblish gem
+====
+On a server running Ubuntu 16.04, `gem which giblish` returns:
+
+ /var/lib/gems/2.6.0/gems/giblish-0.7.0/lib/giblish.rb
+
+and the template hook can be found under
+
+ /var/lib/gems/2.6.0/gems/giblish-0.7.0/scripts/hooks/post-receive.example
+====
+
+ . Rename the copy to `post-receive`
+ . Tweak the configuration variables of the copy to suite your use case.
+ . Move your copy to the `hooks` directory of your _Main Repo_.
+ . Set the execute permission using `chmod +x post-receive`
+
+That's it. You can now push to your _Main Repo_ and the `post-receive` hook will run `giblish` on the branches that you set it up to.
+
+=== Setup the git hook and Jenkins scenario
+
+TBD...
+
+First, follow the steps described in <<common_setup>>. Then proceed with the steps below.
+
+==== Sequence for generating documents
+
+The following image shows how the sequence from user commit to generated documents.
+
+.Sequence diagram for generating docs from adoc
+image::Render Documents.png[]
+
+[appendix]
+== Template scripts
+
+.The giblish `post-receive` template git hook
+[%collapsible]
+====
+[source,bash]
+----
+include::../scripts/hooks/post-receive.example[]
+----
+====
+
+=== post-update hook
+
+Below is an example of a `post-update` hook that triggers Jenkins jobs after a push to a git repo. This hook should be installed on the server side git repository to trigger Jenkins builds
+
+.Example of a git hook triggering Jenkins builds
+[%collapsible]
+====
+[source,bash]
+----
+include::../docgen/scripts/githook_examples/post-update.example[]
+----
+====

data/docs/howtos/trigger_generation_im/docgen_github.puml

@@ -0,0 +1,51 @@
+@startuml
+!theme cerulean-outline
+' !theme spacelab
+hide footbox
+autonumber
+
+title "Generate docs via GitHub web hook"
+
+box "GitHub" #EEEEEE
+actor       Editor       as Ed
+participant GitHub       as GitHub
+end box
+
+box "Document Hosting Server" #EEEEEE
+participant "Web Server" as Webserv
+participant "Passenger"   as Pass
+participant "Document\nGenerator"   as Docgen
+note right of Docgen
+  This could be
+  a sinatra-based
+  application that 
+  use giblish' helper
+  classes.
+end note
+end box
+
+
+Ed -> GitHub     : push doc update\nto repository
+GitHub -> Webserv : send POST request
+Webserv -> Pass : hand over\nPOST request
+Pass -> Docgen : hand over\nPOST request
+Docgen -> Docgen : generate\ndocumentation
+note left
+  The documents are generated and stored\n
+  somewhere in the file system known to\n
+  the web server.
+end note
+/' You can also declare:
+
+== Using raw git hook ==
+
+Ed -> GitHub     : push doc update to repository
+GitHub -> Web server : send POST request
+Webserv -> Pass : hand over POST request to passenger
+Pass -> Docgen : hand over POST request to Sinatra
+Docgen -> Docgen : generate documentation
+  '/
+
+@enduml
+
+