From ad475307fde84530286ffb17df6ce7d221766ec2 Mon Sep 17 00:00:00 2001 From: Oliver Drotbohm Date: Wed, 20 Jul 2022 15:28:49 +0200 Subject: [PATCH] GH-6 - Initial skeleton for project reference documentation. --- .github/workflows/build.yaml | 2 +- pom.xml | 221 +++++++++++++++++++++--- spring-modulith-distribution/pom.xml | 38 ++++ src/docs/asciidoc/00-preface.adoc | 11 ++ src/docs/asciidoc/10-fundamentals.adoc | 28 +++ src/docs/asciidoc/20-verification.adoc | 10 ++ src/docs/asciidoc/30-testing.adoc | 9 + src/docs/asciidoc/40-events.adoc | 9 + src/docs/asciidoc/50-moments.adoc | 9 + src/docs/asciidoc/60-documentation.adoc | 9 + src/docs/asciidoc/index.adoc | 27 +++ src/docs/resources/assemblies/docs.xml | 18 ++ 12 files changed, 365 insertions(+), 26 deletions(-) create mode 100644 spring-modulith-distribution/pom.xml create mode 100644 src/docs/asciidoc/00-preface.adoc create mode 100644 src/docs/asciidoc/10-fundamentals.adoc create mode 100644 src/docs/asciidoc/20-verification.adoc create mode 100644 src/docs/asciidoc/30-testing.adoc create mode 100644 src/docs/asciidoc/40-events.adoc create mode 100644 src/docs/asciidoc/50-moments.adoc create mode 100644 src/docs/asciidoc/60-documentation.adoc create mode 100644 src/docs/asciidoc/index.adoc create mode 100644 src/docs/resources/assemblies/docs.xml diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index 43e9494e..46e3903c 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -2,7 +2,7 @@ name: CI Build on: push: - branches: [ main ] + branches: [ main, hacking/docs ] pull_request: branches: [ main ] diff --git a/pom.xml b/pom.xml index d147f046..b042c048 100644 --- a/pom.xml +++ b/pom.xml @@ -34,9 +34,11 @@ 0.23.1 + 3.4.0 2021.2.4 UTF-8 UTF-8 + 0.2.5 @@ -157,7 +159,7 @@ limitations under the License. org.jfrog.buildinfo artifactory-maven-plugin - 3.4.0 + ${artifactory-maven-plugin.version} false @@ -216,47 +218,216 @@ limitations under the License. + documentation + + + spring-modulith-distribution + + + ${project.build.directory}/shared-resources + ${project.build.directory}/docs-source + ${project.build.directory}/generated-docs + true true + true + true + + + + + - org.jfrog.buildinfo - artifactory-maven-plugin - 3.4.0 - false + com.googlecode.maven-download-plugin + download-maven-plugin + 1.6.8 - deploy-docs-to-artifactory + unpack-doc-resources + generate-resources - publish + wget - - https://repo.spring.io - *-docs.zip - ${env.ARTIFACTORY_USERNAME} - ${env.ARTIFACTORY_PASSWORD} - temp-private-local - temp-private-local - - - Documentation build for Spring Modulith ${project.version} - 1 - - - spring-modulith-docs - spring-modulith-docs - false - docs - + https://repo.spring.io/release/io/spring/docresources/spring-doc-resources/${spring-doc-resources.version}/spring-doc-resources-${spring-doc-resources.version}.zip + true + ${generated-asciidoc-sources.directory} + + + + + + + org.apache.maven.plugins + maven-antrun-plugin + 1.8 + + + create-generated-docs-resources + generate-resources + + run + + + + + + + + + + + + + + + + + + org.jfrog.buildinfo + artifactory-maven-plugin + + + + + + + + + + org.asciidoctor + asciidoctor-maven-plugin + 2.2.2 + + + org.jruby + jruby + 9.2.6.0 + + + + + + + html + generate-resources + + process-asciidoc + + + ${generated-asciidoc-sources.directory} + index.adoc + ${generated-docs.directory} + highlight.js + + js/highlight + github + true + true + ./css + spring.css + left + + + + + + + book + + shared + font + false + images + ${project.version} + ${project.name} + ${project.version} + ${spring.version} + 4 + true + + + + + + + + org.apache.maven.plugins + maven-assembly-plugin + + + docs + + single + + package + + + src/docs/resources/assemblies/docs.xml + + spring-modulith-${project.version} + true + + + + + + + + + org.jfrog.buildinfo + artifactory-maven-plugin + artifactory-maven-plugin.version + false + + + deploy-docs-to-artifactory + + publish + + deploy + + + https://repo.spring.io + *-docs.zip + ${env.ARTIFACTORY_USERNAME} + ${env.ARTIFACTORY_PASSWORD} + temp-private-local + temp-private-local + + + Documentation publication build for Spring Modulith ${project.version} + 1 + + + spring-modulith-docs + spring-modulith-docs + false + docs + + + + + + + + diff --git a/spring-modulith-distribution/pom.xml b/spring-modulith-distribution/pom.xml new file mode 100644 index 00000000..fdc57828 --- /dev/null +++ b/spring-modulith-distribution/pom.xml @@ -0,0 +1,38 @@ + + + + 4.0.0 + + spring-modulith-distribution + + pom + + Spring Modulith - Distribution + Reference documentation and Javadoc + + + org.springframework.experimental + spring-modulith + 0.1.0-SNAPSHOT + ../pom.xml + + + + ${basedir}/.. + + + + + + org.apache.maven.plugins + maven-assembly-plugin + + + org.asciidoctor + asciidoctor-maven-plugin + + + + + diff --git a/src/docs/asciidoc/00-preface.adoc b/src/docs/asciidoc/00-preface.adoc new file mode 100644 index 00000000..bd9666dd --- /dev/null +++ b/src/docs/asciidoc/00-preface.adoc @@ -0,0 +1,11 @@ +[preface] +[[preface]] += Preface + +[[preface.subheadline]] +== Subheadline +Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. +Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. +Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. +Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. + diff --git a/src/docs/asciidoc/10-fundamentals.adoc b/src/docs/asciidoc/10-fundamentals.adoc new file mode 100644 index 00000000..18aec162 --- /dev/null +++ b/src/docs/asciidoc/10-fundamentals.adoc @@ -0,0 +1,28 @@ +[[fundamentals]] += Fundamentals + +Spring Modulith supports developers implementing logical modules in Spring Boot applications. +I allows them to apply structural validation, document the module arrangement, run integration tests for individual modules, observe the modules interaction at runtime and generally implement module interaction in a loosely-coupled way. +This section will discuss the fundamental concepts that developers need to understand before diving into the technical support. + +[[fundamentals.modules]] +== Application modules + +In a Spring Boot application, an application module is a unit of functionality that consists of the following parts: + +* An API exposed to other modules implemented by Spring bean instances and application events published by the module, usually referred to as _provided interface_. +* Internal implementation components that are not supposed to be accessed by other modules. +* References to API exposed by other modules in the form of Spring bean dependencies, application events listened to and configuration properties exposed. + +Spring Moduliths provides different ways of expressing modules, primarily differing in the level of complexity involved in the overall arrangement. +This allows developers to start simple and naturally move to more sophisticated means as and if needed. + + + +=== Simple Application Modules + + + +=== Advanced Application Modules + +=== Named Interfaces diff --git a/src/docs/asciidoc/20-verification.adoc b/src/docs/asciidoc/20-verification.adoc new file mode 100644 index 00000000..ee0ea774 --- /dev/null +++ b/src/docs/asciidoc/20-verification.adoc @@ -0,0 +1,10 @@ +[[verification]] += Verifying Application Module Structure + +[[verification.subheadline]] +== Subheadline +Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. +Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. +Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. +Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. + diff --git a/src/docs/asciidoc/30-testing.adoc b/src/docs/asciidoc/30-testing.adoc new file mode 100644 index 00000000..3a08fc03 --- /dev/null +++ b/src/docs/asciidoc/30-testing.adoc @@ -0,0 +1,9 @@ +[[testing]] += Integration Testing Application Modules + +[[testing.subheadline]] +== Subheadline +Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. +Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. +Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. +Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. diff --git a/src/docs/asciidoc/40-events.adoc b/src/docs/asciidoc/40-events.adoc new file mode 100644 index 00000000..db75909e --- /dev/null +++ b/src/docs/asciidoc/40-events.adoc @@ -0,0 +1,9 @@ +[[events]] += Working with Application Events + +[[events.subheadline]] +== Subheadline +Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. +Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. +Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. +Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. diff --git a/src/docs/asciidoc/50-moments.adoc b/src/docs/asciidoc/50-moments.adoc new file mode 100644 index 00000000..ea06fd55 --- /dev/null +++ b/src/docs/asciidoc/50-moments.adoc @@ -0,0 +1,9 @@ +[[moments]] += Moments -- a Passage of Time Events API + +[[moments.subheadline]] +== Subheadline +Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. +Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. +Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. +Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. diff --git a/src/docs/asciidoc/60-documentation.adoc b/src/docs/asciidoc/60-documentation.adoc new file mode 100644 index 00000000..9a7c74a1 --- /dev/null +++ b/src/docs/asciidoc/60-documentation.adoc @@ -0,0 +1,9 @@ +[[documentation]] += Documenting Application Modules + +[[documentation.subheadline]] +== Subheadline +Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. +Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. +Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. +Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. diff --git a/src/docs/asciidoc/index.adoc b/src/docs/asciidoc/index.adoc new file mode 100644 index 00000000..a84278ee --- /dev/null +++ b/src/docs/asciidoc/index.adoc @@ -0,0 +1,27 @@ += Spring Modulith -- Reference documentation +Oliver Drotbohm +:revnumber: {version} +:revdate: {localdate} +:toc: left + +© 2022 The original authors. + +NOTE: Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically. + +:leveloffset: +1 + +include::00-preface.adoc[] + +include::10-fundamentals.adoc[] + +include::20-verification.adoc[] + +include::30-testing.adoc[] + +include::40-events.adoc[] + +include::50-moments.adoc[] + +include::60-documentation.adoc[] + +:leveloffset: -1 diff --git a/src/docs/resources/assemblies/docs.xml b/src/docs/resources/assemblies/docs.xml new file mode 100644 index 00000000..63b648e0 --- /dev/null +++ b/src/docs/resources/assemblies/docs.xml @@ -0,0 +1,18 @@ + + + docs + + dir + zip + + false + + + + target/generated-docs + reference + + +