Features/165 generate html docs

aadarchi-maven-plugin/pom.xml

@@ -12,6 +12,12 @@
 	<name>Agile Architecture Documentation System : Maven plugin</name>
 
 	<dependencies>
+	<!-- used to invoke asciidoctor-maven-plugin in a controlled way -->
+		<dependency>
+			<groupId>org.twdata.maven</groupId>
+			<artifactId>mojo-executor</artifactId>
+			<version>2.4.0</version>
+		</dependency>
 		<dependency>
 			<groupId>javax.enterprise</groupId>
 			<artifactId>cdi-api</artifactId>

aadarchi-maven-plugin/src/it/2_generate_html_docs/pom.xml

@@ -0,0 +1,132 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+        <groupId>io.github.Riduidel.agile-architecture-documentation-system</groupId>
+        <version>0.0.12-SNAPSHOT</version>
+    <modelVersion>4.0.0</modelVersion>
+
+    <artifactId>simple</artifactId>
+    <name>Agile Architecture Documentation System : System documentation generator</name>
+    <description>Using agile architecture documentation system to document agile archiecture documentation system</description>
+    <properties>
+        <kroki.server.url>https://kroki.io</kroki.server.url>
+        <version.java>11</version.java>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
+        <asciidoctor.highlighter>highlightjs</asciidoctor.highlighter>
+        <asciidoc.source.docs.directory>src/docs/asciidoc</asciidoc.source.docs.directory>
+        <asciidoc.source.slides.directory>src/slides/asciidoc</asciidoc.source.slides.directory>
+        <asciidoc.target.base.directory>${project.build.directory}/asciidoc</asciidoc.target.base.directory>
+        <asciidoc.target.docs.directory>${asciidoc.target.base.directory}/docs</asciidoc.target.docs.directory>
+        <asciidoc.target.slides.directory>${asciidoc.target.base.directory}/slides</asciidoc.target.slides.directory>
+        <agile.architecture.main.class>org.ndx.agile.architecture.base.ArchitectureDocumentationBuilder</agile.architecture.main.class>
+        <agile.architecture.output.dir>${project.build.directory}/structurizr</agile.architecture.output.dir>
+        <agile.architecture.output.diagrams>${agile.architecture.output.dir}/diagrams</agile.architecture.output.diagrams>
+        <agile.architecture.output.enhancements>${agile.architecture.output.dir}/enhancements</agile.architecture.output.enhancements>
+
+        <!-- tag::issues-url[] -->
+        <!-- TODO set a valid value to have doc improvement enabled -->
+        <issues.url>https://github.com/Riduidel/agile-architecture-documentation-system/issues</issues.url>
+        <!-- end::issues-url[] -->
+
+        <!-- See latest version here: https://mvnrepository.com/artifact/org.asciidoctor/asciidoctor-maven-plugin -->
+        <version.asciidoctor.maven.plugin>2.1.0</version.asciidoctor.maven.plugin>
+        <!-- See latest version here: https://mvnrepository.com/artifact/org.asciidoctor/asciidoctorj-pdf -->
+        <version.asciidoctorj.pdf>1.5.4</version.asciidoctorj.pdf>
+        <!-- See latest version here: https://mvnrepository.com/artifact/org.asciidoctor/asciidoctorj -->
+        <version.asciidoctorj>2.4.3</version.asciidoctorj>
+        <!-- See latest version here: https://mvnrepository.com/artifact/org.asciidoctor/asciidoctorj-revealjs -->
+        <version.asciidoctor.revealjs>4.1.0</version.asciidoctor.revealjs>
+        <!-- See latest version here: https://mvnrepository.com/artifact/org.asciidoctor/asciidoctorj-diagram -->
+        <version.asciidoctor.kroki>0.5.0</version.asciidoctor.kroki>
+        <!-- See latest version here https://mvnrepository.com/artifact/org.jruby/jruby -->
+        <version.jruby>9.2.9.0</version.jruby>
+        <!-- See latest version here: https://github.com/hakimel/reveal.js/releases -->
+        <version.revealjs>3.9.2</version.revealjs>
+    </properties>
+
+    <issueManagement>
+        <url>${issues.url}</url>
+    </issueManagement>
+
+    <!-- We need the rubygems releases to use Kroki and asciidoc-revealjs
+	See https://github.com/Riduidel/agile-architecture-documentation-system/issues/159 for the weird protocol -->
+    <repositories>
+        <repository>
+            <id>mavengems</id>
+            <url>mavengem:https://rubygems.org</url>
+        </repository>
+    </repositories>
+
+    <dependencies>
+		<dependency>
+			<groupId>rubygems</groupId>
+			<artifactId>asciidoctor-kroki</artifactId>
+			<version>${version.asciidoctor.kroki}</version>
+			<type>gem</type>
+			<!-- Avoid downloading gems included in AsciidoctorJ -->
+			<exclusions>
+				<exclusion>
+					<groupId>rubygems</groupId>
+					<artifactId>asciidoctor</artifactId>
+				</exclusion>
+				<exclusion>
+					<groupId>rubygems</groupId>
+					<artifactId>thread_safe</artifactId>
+				</exclusion>
+				<exclusion>
+					<groupId>rubygems</groupId>
+					<artifactId>concurrent-ruby</artifactId>
+				</exclusion>
+			</exclusions>
+		</dependency>
+    </dependencies>
+
+    <build>
+		<extensions>
+			<extension>
+				<!-- this allows us to download gems -->
+				<groupId>org.torquebox.mojo</groupId>
+				<artifactId>mavengem-wagon</artifactId>
+				<version>1.0.3</version>
+			</extension>
+		</extensions>
+        <plugins>
+			<plugin>
+				<groupId>de.saumya.mojo</groupId>
+				<artifactId>gem-maven-plugin</artifactId>
+				<version>2.0.1</version>
+				<configuration>
+					<jrubyVersion>${version.jruby}</jrubyVersion>
+					<gemHome>${project.build.directory}/gems</gemHome>
+					<gemPath>${project.build.directory}/gems</gemPath>
+				</configuration>
+				<executions>
+					<!-- Install required gems in target directory -->
+					<execution>
+						<id>install-gems</id>
+						<goals>
+							<goal>initialize</goal>
+						</goals>
+						<phase>initialize</phase>
+					</execution>
+				</executions>
+			</plugin>
+            <plugin>
+                <groupId>@project.groupId@</groupId>
+                <artifactId>aadarchi-maven-plugin</artifactId>
+                <version>@project.version@</version>
+                <executions>
+                    <execution>
+                        <goals>
+                            <goal>generate-model</goal>
+                            <goal>generate-html-docs</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>

aadarchi-maven-plugin/src/it/2_generate_html_docs/src/architecture/resources/workspace.dsl

@@ -0,0 +1,109 @@
+workspace "agile-architecture-documentation-system" {
+
+	model {
+		Architect_1 = person "Architect" "The architect as team scribe is the writer of this kind of documentation."
+		Stakeholder_2 = person "Stakeholder" "All project stakeholders are readers of this kind of documentation."
+		Agile_architecture_documentation_3 = softwareSystem "Agile architecture documentation" {
+			base_10 = container "base" {
+				SCMReadmeReader_17 = component "SCMReadmeReader" {
+				}
+				maven_metadata_inferer_37 = component "maven-metadata-inferer" {
+				}
+				adr_tickets_extractor_31 = component "adr-tickets-extractor" {
+				}
+				GraphEmitter_16 = component "GraphEmitter" {
+				}
+				ArchitectureEnhancer_15 = component "ArchitectureEnhancer" {
+				}
+				github_scm_handler_25 = component "github-scm-handler" {
+				}
+				ImplicitIncludeManager_13 = component "ImplicitIncludeManager" {
+				}
+				cdi_config_extension_35 = component "cdi-config-extension" {
+				}
+				SCMLinkGenerator_11 = component "SCMLinkGenerator" {
+				}
+				gitlab_scm_handler_28 = component "gitlab-scm-handler" {
+				}
+				DocumentsCollector_12 = component "DocumentsCollector" {
+				}
+				ArchitectureDocumentationBuilder_14 = component "ArchitectureDocumentationBuilder" {
+				}
+			}
+			asciidoc_39 = container "asciidoc" {
+			}
+			maven_8 = container "maven" {
+			}
+			archetype_6 = container "archetype" {
+			}
+		}
+		ArchitectureEnhancer_15 -> ImplicitIncludeManager_13 "Generates includes for all enhancers" ""
+		Architect_1 -> maven_8 "Generates documentation" ""
+		ArchitectureEnhancer_15 -> DocumentsCollector_12 "Collects documents in source folder" ""
+		ArchitectureEnhancer_15 -> adr_tickets_extractor_31 "Produces ADR reporting" ""
+		SCMReadmeReader_17 -> github_scm_handler_25 "Get project readme" ""
+		Architect_1 -> archetype_6 "Bootstrap a valid project" ""
+		SCMReadmeReader_17 -> gitlab_scm_handler_28 "Get project readme" ""
+		ArchitectureEnhancer_15 -> GraphEmitter_16 "Generates diagrams in PlantUML format" ""
+		maven_8 -> ArchitectureDocumentationBuilder_14 "Invokes that Java executable during maven build" ""
+		adr_tickets_extractor_31 -> github_scm_handler_25 "Read tickets from GitHub if configured so" ""
+		ArchitectureEnhancer_15 -> SCMLinkGenerator_11 "Generates links to SCM sources" ""
+		ArchitectureDocumentationBuilder_14 -> ArchitectureEnhancer_15 "Adds information to initial architecture description" ""
+		maven_8 -> base_10 "Generates diagrams and asciidoc includes" ""
+		maven_8 -> asciidoc_39 "Generates documentation as usable text in HTML/PDF/..." ""
+		SCMLinkGenerator_11 -> gitlab_scm_handler_28 "Get project source link" ""
+		adr_tickets_extractor_31 -> gitlab_scm_handler_28 "Read tickets from Gitlab if configured so" ""
+		ArchitectureDocumentationBuilder_14 -> maven_metadata_inferer_37 "Infer most of element details from Maven infos" ""
+		ArchitectureEnhancer_15 -> SCMReadmeReader_17 "Includes elements readme when they exist" ""
+		SCMLinkGenerator_11 -> github_scm_handler_25 "Get project source link" ""
+		ArchitectureDocumentationBuilder_14 -> cdi_config_extension_35 "Eases out some CDI code" ""
+		Stakeholder_2 -> Agile_architecture_documentation_3 "Read" ""
+		Architect_1 -> Agile_architecture_documentation_3 "Writes" ""
+		SCMReadmeReader_17 -> github_scm_handler_25 "Get project readme" ""
+		SCMReadmeReader_17 -> gitlab_scm_handler_28 "Get project readme" ""
+		adr_tickets_extractor_31 -> gitlab_scm_handler_28 "Read tickets from Gitlab if configured so" ""
+		adr_tickets_extractor_31 -> github_scm_handler_25 "Read tickets from GitHub if configured so" ""
+		ArchitectureEnhancer_15 -> DocumentsCollector_12 "Collects documents in source folder" ""
+		ArchitectureEnhancer_15 -> SCMLinkGenerator_11 "Generates links to SCM sources" ""
+		ArchitectureEnhancer_15 -> SCMReadmeReader_17 "Includes elements readme when they exist" ""
+		ArchitectureEnhancer_15 -> ImplicitIncludeManager_13 "Generates includes for all enhancers" ""
+		ArchitectureEnhancer_15 -> GraphEmitter_16 "Generates diagrams in PlantUML format" ""
+		ArchitectureEnhancer_15 -> adr_tickets_extractor_31 "Produces ADR reporting" ""
+		SCMLinkGenerator_11 -> github_scm_handler_25 "Get project source link" ""
+		SCMLinkGenerator_11 -> gitlab_scm_handler_28 "Get project source link" ""
+		ArchitectureDocumentationBuilder_14 -> ArchitectureEnhancer_15 "Adds information to initial architecture description" ""
+		ArchitectureDocumentationBuilder_14 -> cdi_config_extension_35 "Eases out some CDI code" ""
+		ArchitectureDocumentationBuilder_14 -> maven_metadata_inferer_37 "Infer most of element details from Maven infos" ""
+		maven_8 -> ArchitectureDocumentationBuilder_14 "Invokes that Java executable during maven build" ""
+		maven_8 -> base_10 "Generates diagrams and asciidoc includes" ""
+		maven_8 -> asciidoc_39 "Generates documentation as usable text in HTML/PDF/..." ""
+	}
+	views {
+		styles {
+			element "Software System" {
+				background #1168bd
+				color #ffffff
+			}
+			element "Person" {
+				shape person
+				background #08427b
+				color #ffffff
+			}
+		}
+        systemContext Agile_architecture_documentation_3 "SystemContext" {
+            include *
+            autoLayout
+        }
+
+        container Agile_architecture_documentation_3 "SystemContainers"  {
+            include *
+            autoLayout
+        }
+
+		component base_10 "baseComponents" {
+            include *
+            autoLayout
+        }
+	}
+
+}

aadarchi-maven-plugin/src/it/2_generate_html_docs/src/docs/asciidoc/01-context.adoc

@@ -0,0 +1,22 @@
+= Context
+:chapter: Context
+include::_notify-bug-admonition.adoc[]
+
+agile-architecture-documentation-system tries to provide a solution to a rather usual, but not so well solved, problem: 
+how to document architecture of a software system with the minimal effort and the maximal result.
+As a consequence, this product tries to help the architect in all possible ways.
+
+== Context diagram
+// This is an example diagram to show how to include a structurizr-generated diagram
+[plantuml, {plantumldir}SystemContext, svg, opts="interactive"]     
+----
+include::{structurizrdir}/SystemContext.plantuml[]
+----
+
+We identify different user profiles:
+
+* the architect as a scribe role, which is responsible for maintaining a correct documentation of the architecture
+* the various stakeholders, be them developers, product owners, ops teams, and so on, which will refer to the produced documentation as an entrypoint.
+
+// This include allows enhancers to have their content include "automagically". Don't remove it!
+include::{enhancements-dir}/_01-context.adoc[leveloffset=+1]

aadarchi-maven-plugin/src/it/2_generate_html_docs/src/docs/asciidoc/02-functional_overview.adoc

@@ -0,0 +1,79 @@
+= Functional Overview
+:chapter: Functional%20Overview
+include::_notify-bug-admonition.adoc[]
+
+This software helps the architect writing a coherent, complete and readable software architecture documentation.
+Usage of this software is quite simple (for a developer).
+
+The first step is to initiate a documentation (which is documented in https://github.com/Riduidel/agile-architecture-documentation-system#install[README.md]).
+
+Then, architect has to write content in all `.adoc` files generated in `src/docs/asciidoc`.
+Notice writing those files will be eased out by using the `Architecture` java class to generate diagrams,
+and the enhancers this project provides.
+
+The enhancers allows architect to have content added to this documentation without having to write it himself.
+Typically, we're able to include README documents, architecture decisions, and more to come later ... (well, provided the users ask for additionnal includes) 
+
+////
+Even though the purpose of technical software documentation isn't to
+explain what the software does in detail, it can be useful to expand on
+the link:/help/documentation/context[context] and summarise what the
+major functions of the software are.
+
+== Intent
+
+This section allows you to summarise what the key functions of the
+system are (use cases, user stories, etc). A functional overview should
+answer the following types of questions:
+
+* Is it clear what the system actually does?
+* Is it clear who the important users are (roles, actors, personas, etc)
+and how the system caters for their needs?
+
+Alternatively, if your software automates a business process or
+workflow, a functional view should answer questions like the following:
+
+* Is it clear what the system does from a process perspective?
+* What are the major processes and flows of information through the
+system?
+
+== Structure
+
+By all means refer to existing documentation if it's available, whether
+that's in the form of functional specifications, use case documents,
+lists of user stories, etc. However, it's often useful to summarise the
+business domain and the functionality provided by the system. Again,
+diagrams can help, and you could use a UML use case diagram or a
+collection of simple wireframes showing the important parts of the user
+interface. Either way, the purpose of this section is to provide a
+functional _overview_.
+
+Alternatively, if your software automates a business process or
+workflow, you could use a flow chart or UML activity diagram to show the
+smaller steps within the process and how they fit together. This is
+particularly useful to highlight aspects such as parallelism,
+concurrency, where businesses processes fork or join, etc.
+
+== Motivation
+
+This doesn't necessarily need to be a long section, with diagrams being
+used to provide an overview. Where a
+link:/help/documentation/context[context section] summarises how the
+software fits into the existing environment, this section describes what
+the system actually does. Again, this is about providing a summary and
+setting the scene rather than comprehensively describing every
+user/system interaction.
+
+== Audience
+
+Technical and non-technical people, inside and outside of the immediate
+software development team.
+
+== Required
+
+Yes, all software documentation should include a summary of the
+functionality provided by the software.
+////
+
+// This include allows enhancers to have their content include "automagically". Don't remove it!
+include::{enhancements-dir}/_02-functional_overview.adoc[leveloffset=+1]