Skip to content

Commit

Permalink
GH-6 - Initial skeleton for project reference documentation.
Browse files Browse the repository at this point in the history
  • Loading branch information
@odrotbohm
odrotbohm committed Jul 27, 2022
1 parent 80cf808 commit ad47530
Show file tree
Hide file tree
Showing 12 changed files with 365 additions and 26 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/build.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ name: CI Build

on:
push:
branches: [ main ]
branches: [ main, hacking/docs ]
pull_request:
branches: [ main ]

Expand Down
221 changes: 196 additions & 25 deletions pom.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>

Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -216,47 +218,216 @@ 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>
</deployProperties>
</configuration>
</execution>
</executions>
</plugin>

</plugins>
</pluginManagement>
</build>
</profile>

Expand Down
38 changes: 38 additions & 0 deletions spring-modulith-distribution/pom.xml
View file
Original file line number Diff line number Diff line change
@@ -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 changes: 11 additions & 0 deletions src/docs/asciidoc/00-preface.adoc
View file
Original file line number Diff line number Diff line change
@@ -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 changes: 28 additions & 0 deletions src/docs/asciidoc/10-fundamentals.adoc
View file
Original file line number Diff line number Diff line change
@@ -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 changes: 10 additions & 0 deletions src/docs/asciidoc/20-verification.adoc
View file
Original file line number Diff line number Diff line change
@@ -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 changes: 9 additions & 0 deletions src/docs/asciidoc/30-testing.adoc
View file
Original file line number Diff line number Diff line change
@@ -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 changes: 9 additions & 0 deletions src/docs/asciidoc/40-events.adoc
View file
Original file line number Diff line number Diff line change
@@ -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 changes: 9 additions & 0 deletions src/docs/asciidoc/50-moments.adoc
View file
Original file line number Diff line number Diff line change
@@ -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.
Loading

0 comments on commit ad47530

Please sign in to comment.