Spring/spring-modulith
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

GH-6 - Initial skeleton for project reference documentation.

Browse Source
This commit is contained in:
Oliver Drotbohm
2022-07-20 15:28:49 +02:00
parent 80cf808012
commit 0fdabdb9e6
13 changed files with 371 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
.github/workflows/docs.yaml vendored
View File

@@ -21,6 +21,9 @@ jobs:
java-version: 17
cache: 'maven'
- name: Setup Graphviz
uses: ts-graphviz/setup-graphviz@v1
- name: Deploy documentation
env:
ARTIFACTORY_USERNAME: ${{ secrets.ARTIFACTORY_USERNAME }}

3
.github/workflows/release.yaml vendored
View File

@@ -34,6 +34,9 @@ jobs:
./mvnw -B clean install -DskipTests
./mvnw -B clean deploy -Psonatype -s settings.xml -Dgpg.passphrase='${{ secrets.GPG_PASSPHRASE }}'
- name: Setup Graphviz
uses: ts-graphviz/setup-graphviz@v1
- name: Deploy documentation
env:
ARTIFACTORY_USERNAME: ${{ secrets.ARTIFACTORY_USERNAME }}

222
pom.xml
View File

@@ -34,9 +34,11 @@
<properties>
<archunit.version>0.23.1</archunit.version>
<artifactory-maven-plugin.version>3.4.0</artifactory-maven-plugin.version>
<jmolecules-bom.version>2021.2.4</jmolecules-bom.version>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
<spring-doc-resources.version>0.2.5</spring-doc-resources.version>
</properties>
@@ -157,7 +159,7 @@ limitations under the License.
<plugin>
<groupId>org.jfrog.buildinfo</groupId>
<artifactId>artifactory-maven-plugin</artifactId>
<version>3.4.0</version>
<version>${artifactory-maven-plugin.version}</version>
<inherited>false</inherited>
<executions>
<execution>
@@ -216,47 +218,217 @@ limitations under the License.
</profile>
<profile>
<id>documentation</id>
<modules>
<module>spring-modulith-distribution</module>
</modules>
<properties>
<shared.resources>${project.build.directory}/shared-resources</shared.resources>
<generated-asciidoc-sources.directory>${project.build.directory}/docs-source</generated-asciidoc-sources.directory>
<generated-docs.directory>${project.build.directory}/generated-docs</generated-docs.directory>
<maven.main.skip>true</maven.main.skip>
<maven.test.skip>true</maven.test.skip>
<maven.install.skip>true</maven.install.skip>
<maven.deploy.skip>true</maven.deploy.skip>
</properties>
<build>
<plugins>
<!--
Unpacks the content of spring-doc-resources into the shared resources folder.
-->
<plugin>
<groupId>org.jfrog.buildinfo</groupId>
<artifactId>artifactory-maven-plugin</artifactId>
<version>3.4.0</version>
<inherited>false</inherited>
<groupId>com.googlecode.maven-download-plugin</groupId>
<artifactId>download-maven-plugin</artifactId>
<version>1.6.8</version>
<executions>
<execution>
<id>deploy-docs-to-artifactory</id>
<id>unpack-doc-resources</id>
<phase>generate-resources</phase>
<goals>
<goal>publish</goal>
<goal>wget</goal>
</goals>
<configuration>
<publisher>
<contextUrl>https://repo.spring.io</contextUrl>
<includePatterns>*-docs.zip</includePatterns>
<username>${env.ARTIFACTORY_USERNAME}</username>
<password>${env.ARTIFACTORY_PASSWORD}</password>
<repoKey>temp-private-local</repoKey>
<snapshotRepoKey>temp-private-local</snapshotRepoKey>
</publisher>
<buildInfo>
<buildName>Documentation build for Spring Modulith ${project.version}</buildName>
<buildRetentionCount>1</buildRetentionCount>
</buildInfo>
<deployProperties>
<zip.name>spring-modulith-docs</zip.name>
<zip.displayname>spring-modulith-docs</zip.displayname>
<zip.deployed>false</zip.deployed>
<zip.type>docs</zip.type>
</deployProperties>
<url>https://repo.spring.io/release/io/spring/docresources/spring-doc-resources/${spring-doc-resources.version}/spring-doc-resources-${spring-doc-resources.version}.zip</url>
<unpack>true</unpack>
<outputDirectory>${generated-asciidoc-sources.directory}</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-antrun-plugin</artifactId>
<version>1.8</version>
<executions>
<execution>
<id>create-generated-docs-resources</id>
<phase>generate-resources</phase>
<goals>
<goal>run</goal>
</goals>
<configuration>
<target>
<!-- All Asciidoctor files to the source directory -->
<copy failonerror="false" todir="${generated-asciidoc-sources.directory}/">
<fileset dir="${project.root}/src/docs/asciidoc" includes="**/*.adoc"/>
</copy>
<!-- All images, too -->
<copy failonerror="false"
todir="${generated-asciidoc-sources.directory}/images/">
<fileset dir="${project.root}/src/docs/asciidoc/images"/>
</copy>
</target>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.jfrog.buildinfo</groupId>
<artifactId>artifactory-maven-plugin</artifactId>
</plugin>
</plugins>
<pluginManagement>
<plugins>
<!--
Asciidoctor
-->
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>2.2.2</version>
<dependencies>
<dependency>
<groupId>org.jruby</groupId>
<artifactId>jruby</artifactId>
<version>9.2.6.0</version>
</dependency>
</dependencies>
<executions>
<execution>
<id>html</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<sourceDirectory>${generated-asciidoc-sources.directory}</sourceDirectory>
<sourceDocumentName>index.adoc</sourceDocumentName>
<outputDirectory>${generated-docs.directory}</outputDirectory>
<sourceHighlighter>highlight.js</sourceHighlighter>
<attributes>
<highlightjsdir>js/highlight</highlightjsdir>
<highlightjs-theme>github</highlightjs-theme>
<linkcss>true</linkcss>
<sectanchors>true</sectanchors>
<stylesdir>./css</stylesdir>
<stylesheet>spring.css</stylesheet>
<toc>left</toc>
</attributes>
</configuration>
</execution>
</executions>
<configuration>
<doctype>book</doctype>
<attributes>
<docinfo>shared</docinfo>
<icons>font</icons>
<sectids>false</sectids>
<imagesdir>images</imagesdir>
<version>${project.version}</version>
<projectName>${project.name}</projectName>
<projectVersion>${project.version}</projectVersion>
<springVersion>${spring.version}</springVersion>
<toclevels>4</toclevels>
<numbered>true</numbered>
</attributes>
</configuration>
</plugin>
<!--
Creates two zip files for download as well as API and reference documentation distribution.
-->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-assembly-plugin</artifactId>
<executions>
<execution>
<id>docs</id>
<goals>
<goal>single</goal>
</goals>
<phase>package</phase>
<configuration>
<descriptors>
<descriptor>src/docs/resources/assemblies/docs.xml</descriptor>
</descriptors>
<finalName>spring-modulith-${project.version}</finalName>
<appendAssemblyId>true</appendAssemblyId>
</configuration>
</execution>
</executions>
</plugin>
<!-- Deploy to Artifactory -->
<plugin>
<groupId>org.jfrog.buildinfo</groupId>
<artifactId>artifactory-maven-plugin</artifactId>
<version>${artifactory-maven-plugin.version}</version>
<inherited>false</inherited>
<executions>
<execution>
<id>deploy-docs-to-artifactory</id>
<goals>
<goal>publish</goal>
</goals>
<phase>deploy</phase>
<configuration>
<publisher>
<contextUrl>https://repo.spring.io</contextUrl>
<includePatterns>*-docs.zip</includePatterns>
<username>${env.ARTIFACTORY_USERNAME}</username>
<password>${env.ARTIFACTORY_PASSWORD}</password>
<repoKey>temp-private-local</repoKey>
<snapshotRepoKey>temp-private-local</snapshotRepoKey>
</publisher>
<buildInfo>
<buildName>Documentation publication build for Spring Modulith ${project.version}</buildName>
<buildRetentionCount>1</buildRetentionCount>
</buildInfo>
<deployProperties>
<zip.name>spring-modulith-docs</zip.name>
<zip.displayname>spring-modulith-docs</zip.displayname>
<zip.deployed>false</zip.deployed>
<zip.type>docs</zip.type>
<archives>*:*:*:*@zip</archives>
</deployProperties>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</pluginManagement>
</build>
</profile>

38
spring-modulith-distribution/pom.xml Normal file
View File

@@ -0,0 +1,38 @@
<?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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<artifactId>spring-modulith-distribution</artifactId>
<packaging>pom</packaging>
<name>Spring Modulith - Distribution</name>
<description>Reference documentation and Javadoc</description>
<parent>
<groupId>org.springframework.experimental</groupId>
<artifactId>spring-modulith</artifactId>
<version>0.1.0-SNAPSHOT</version>
<relativePath>../pom.xml</relativePath>
</parent>
<properties>
<project.root>${basedir}/..</project.root>
</properties>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-assembly-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>

11
src/docs/asciidoc/00-preface.adoc Normal file
View File

@@ -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.

28
src/docs/asciidoc/10-fundamentals.adoc Normal file
View File

@@ -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

10
src/docs/asciidoc/20-verification.adoc Normal file
View File

@@ -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.

9
src/docs/asciidoc/30-testing.adoc Normal file
View File

@@ -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.

9
src/docs/asciidoc/40-events.adoc Normal file
View File

@@ -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.

9
src/docs/asciidoc/50-moments.adoc Normal file
View File

@@ -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.

9
src/docs/asciidoc/60-documentation.adoc Normal file
View File

@@ -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.

27
src/docs/asciidoc/index.adoc Normal file
View File

@@ -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

18
src/docs/resources/assemblies/docs.xml Normal file
View File

@@ -0,0 +1,18 @@
<?xml version="1.0" encoding="UTF-8"?>
<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2 https://maven.apache.org/xsd/assembly-1.1.2.xsd">
<id>docs</id>
<formats>
<format>dir</format>
<format>zip</format>
</formats>
<includeBaseDirectory>false</includeBaseDirectory>
<fileSets>
<fileSet>
<!--
Adds reference manual (html and pdf) to the distribution archive under the 'docs/reference'.
-->
<directory>target/generated-docs</directory>
<outputDirectory>reference</outputDirectory>
</fileSet>
</fileSets>
</assembly>