Merge pull request #16 from pvlugter/antora

Convert docs to asciidoc/antora

Author: sleipnir

.travis.yml

@@ -13,15 +13,16 @@ jobs:
           tags: true
           repo: cloudstateio/springboot-support
 
+    - stage: validate_docs
+      script: make -C docs
+
     - stage: deploy_docs
-      name: deploy docs to cloudstate.io
-      if: repo = cloudstateio/springboot-support AND ((branch = master AND type = push) OR tag =~ ^v)
-      language: scala
-      install: true
-      script: cd docs && sbt deploy
+      if: repo = cloudstateio/springboot-support AND tag =~ ^v
+      script: make -C docs deploy
 
 stages:
   - build
+  - validate_docs
   - deploy_docs
 
 env:

docs/.gitignore

@@ -0,0 +1,3 @@
+/.cache/
+/.deploy/
+/build/

docs/Makefile

@@ -0,0 +1,55 @@
+# Make Cloudstate Spring Boot documentation
+
+module   := springboot
+upstream := cloudstateio/springboot-support
+branch   := docs/current
+sources  := src build/src/managed
+
+cloudstate_antora_download := https://github.com/cloudstateio/cloudstate-antora/raw/master/cloudstate-antora
+cloudstate_antora := .cache/bin/cloudstate-antora
+descriptor := build/site.yml
+src_managed := build/src/managed
+managed_partials := ${src_managed}/modules/springboot/partials
+
+.SILENT:
+
+build: clean managed validate html
+
+${cloudstate_antora}:
+	mkdir -p $$(dirname ${cloudstate_antora})
+	curl -Lo ${cloudstate_antora} ${cloudstate_antora_download}
+	chmod +x ${cloudstate_antora}
+
+clean-cache:
+	rm -rf .cache
+
+update: clean-cache ${cloudstate_antora}
+
+clean: ${cloudstate_antora}
+	${cloudstate_antora} clean
+
+managed: attributes
+	mkdir -p "${src_managed}"
+	cp src/antora.yml "${src_managed}/antora.yml"
+
+attributes: ${cloudstate_antora}
+	mkdir -p "${managed_partials}"
+	${cloudstate_antora} version | xargs -0  printf ":cloudstate-springboot-lib-version: %s" \
+		> "${managed_partials}/attributes.adoc"
+
+${descriptor}: ${cloudstate_antora}
+	mkdir -p $$(dirname ${descriptor})
+	${cloudstate_antora} source --preview --upstream ${upstream} ${sources} > build/source.yml
+	${cloudstate_antora} site --preview --exclude ${module} build/source.yml > ${descriptor}
+
+validate: ${descriptor}
+	${cloudstate_antora} validate ${descriptor}
+
+html: ${descriptor}
+	${cloudstate_antora} build ${descriptor}
+
+validate-links: ${cloudstate_antora}
+	${cloudstate_antora} validate --no-xrefs --links --links-config config/validate-links.json
+
+deploy: clean managed
+	${cloudstate_antora} deploy --module ${module} --upstream ${upstream} --branch ${branch} ${sources}

docs/README.md

@@ -1,23 +1,19 @@
 # Cloudstate Spring Boot documentation
 
-Documentation source for Cloudstate Spring Boot Support, published to https://cloudstate.io/docs/springboot/current/
+The Cloudstate documentation is built using [Antora](https://antora.org) with Asciidoc sources.
 
-To build the docs with [sbt](https://www.scala-sbt.org):
+The build is defined in the [Makefile](Makefile) and requires `make`, `bash`, and `docker`.
+
+To build the documentation run:
 
 ```
-sbt paradox
+make
 ```
 
-Can also first start the sbt interactive shell with `sbt`, then run commands.
-
-The documentation can be viewed locally by opening the generated pages:
+The generated documentation site will be available in the `build/site` directory:
 
 ```
-open target/paradox/site/main/index.html
+open build/site/index.html
 ```
 
-To watch files for changes and rebuild docs automatically:
-
-```
-sbt ~paradox
-```
+Documentation will be automatically deployed on tagged versions, in the Travis CI builds.

docs/build.sbt

@@ -0,0 +1,5 @@
+{
+  "ignorePatterns": [
+    { "pattern": "^http://maven\\.apache\\.org/POM" }
+  ]
+}

docs/config/validate-links.json

@@ -0,0 +1,2 @@
+name: ""
+version: master

docs/project/build.properties

@@ -1,4 +1,4 @@
-//#shopping-cart-entity
+// tag::shopping-cart-entity[]
 /**
  * An event sourced entity.
  */
@@ -84,9 +84,9 @@ public Empty removeItem(Shoppingcart.RemoveLineItem item, CommandContext ctx) {
         return Empty.getDefaultInstance();
     }
 }
-//#shopping-cart-entity
+// end::shopping-cart-entity[]
 
-//#shopping-cart-configuration
+// tag::shopping-cart-configuration[]
 import com.example.shoppingcart.Shoppingcart;
 import com.google.protobuf.Descriptors;
 import org.springframework.context.annotation.Bean;
@@ -105,9 +105,9 @@ public Descriptors.FileDescriptor[] shoppingCartEntityFileDescriptors() {
         return new Descriptors.FileDescriptor[]{com.example.shoppingcart.persistence.Domain.getDescriptor()};
     }
 }
-//#shopping-cart-configuration
+// end::shopping-cart-configuration[]
 
-//#shopping-cart-main
+// tag::shopping-cart-main[]
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 import io.cloudstate.springboot.starter.autoconfigure.EnableCloudstate;
@@ -117,9 +117,9 @@ public Descriptors.FileDescriptor[] shoppingCartEntityFileDescriptors() {
 public class Main {
     public static void main(String[] args) { SpringApplication.run(Main.class, args); }
 }
-//#shopping-cart-main
+// end::shopping-cart-main[]
 
-//#shopping-cart-descriptors
+// tag::shopping-cart-descriptors[]
 @Bean(name = "shoppingCartEntityServiceDescriptor")
 public Descriptors.ServiceDescriptor serviceDescriptor() {
     return Shoppingcart.getDescriptor().findServiceByName("ShoppingCart");
@@ -129,9 +129,9 @@ public Descriptors.ServiceDescriptor serviceDescriptor() {
 public Descriptors.FileDescriptor[] fileDescriptors() {
    return new Descriptors.FileDescriptor[] {com.example.shoppingcart.persistence.Domain.getDescriptor()};
 }
-//#shopping-cart-descriptors
+// end::shopping-cart-descriptors[]
 
-//#shopping-cart-descriptors-alternative
+// tag::shopping-cart-descriptors-alternative[]
 @Bean
 public Descriptors.ServiceDescriptor shoppingCartEntityServiceDescriptor() {
    return Shoppingcart.getDescriptor().findServiceByName("ShoppingCart");
@@ -141,9 +141,9 @@ public Descriptors.ServiceDescriptor shoppingCartEntityServiceDescriptor() {
 public Descriptors.FileDescriptor[] shoppingCartEntityFileDescriptors() {
     return new Descriptors.FileDescriptor[] {com.example.shoppingcart.persistence.Domain.getDescriptor()};
 }
-//#shopping-cart-descriptors-alternative
+// end::shopping-cart-descriptors-alternative[]
 
-//#shopping-cart-descriptors-static
+// tag::shopping-cart-descriptors-static[]
 @EntityServiceDescriptor
 public static Descriptors.ServiceDescriptor getDescriptor() {
     return Shoppingcart.getDescriptor().findServiceByName("ShoppingCart");
@@ -153,4 +153,4 @@ public static Descriptors.ServiceDescriptor getDescriptor() {
 public static Descriptors.FileDescriptor[] getAdditionalDescriptors() {
     return new Descriptors.FileDescriptor[]{com.example.shoppingcart.persistence.Domain.getDescriptor()};
 }
-//#shopping-cart-descriptors-static
+// end::shopping-cart-descriptors-static[]

docs/project/plugins.sbt

@@ -0,0 +1,6 @@
+* xref:index.adoc[Implementing in Spring Boot]
+** xref:gettingstarted.adoc[Getting started]
+** xref:configuration.adoc[Configuration]
+** xref:cdi.adoc[Context Injection]
+** xref:conventions.adoc[Conventions and Restrictions]
+** xref:examples.adoc[Examples]

docs/src/antora.yml

@@ -1,49 +1,46 @@
-# Context Injection
+= Context Injection
 
-As we saw in the Getting Started example, it is perfectly possible to inject any Bean available in Spring into a 
-Cloudstate entity class.
-It is also possible to use the annotations present in the javax.inject package 
-([JSR330](https://jcp.org/en/jsr/detail?id=330)). 
+As we saw in the Getting Started example, it is perfectly possible to inject any Bean available in Spring into a Cloudstate entity class.
+It is also possible to use the annotations present in the javax.inject package (https://jcp.org/en/jsr/detail?id=330[JSR330]).
 The Cloudstate Springboot Support library already includes the necessary dependencies so you don't have to worry about it.
 
-You can annotate your entity classes with Spring `@Component` or `@Service` annotations but we have created a convenient 
-annotation that we call `@CloudstateEntityBean` that can be used for that too.
+You can annotate your entity classes with Spring `@Component` or `@Service` annotations but we have created a convenient  annotation that we call `@CloudstateEntityBean` that can be used for that too.
 
-## JSR330
+== JSR330
 
-The Cloudstate Spring Boot Support library supports JSR330 within the scope of the support provided by Spring itself to 
-this specification.
-Note that the Cloudstate Java Support library on which we depend allows you to bind Cloudstate and any other DI container 
-you want. However, no specific module for any of these other containers has yet been made.
+The Cloudstate Spring Boot Support library supports JSR330 within the scope of the support provided by Spring itself to this specification.
+Note that the Cloudstate Java Support library on which we depend allows you to bind Cloudstate and any other DI container you want.
+However, no specific module for any of these other containers has yet been made.
 
 Feel free to contribute or suggest support for more runtimes.
 
-## Injecting EntityId and Cloudstate Context Objects
+== Injecting EntityId and Cloudstate Context Objects
 
 You can use the `@EntityId` annotation to access the managed entity's id.
-It is also possible to have access to the EventSourcedEntityCreationContext created during the activation of the object 
-by Cloudstate. However for this you will need to annotate the Context property with the annotation @CloudstateContext 
-as in the example below:
+It is also possible to have access to the EventSourcedEntityCreationContext created during the activation of the object by Cloudstate.
+However for this you will need to annotate the Context property with the annotation @CloudstateContext as in the example below:
 
-```java
+[source,java]
+----
 @EntityId
 private String entityId;
 
 @CloudstateContext
 private EventSourcedContext context;
-```
+----
 
-### Using properties instead constructors
+=== Using properties instead constructors
 
-It is currently not possible to inject Cloudstate's EntityId and Context properties via constructor. 
+It is currently not possible to inject Cloudstate's EntityId and Context properties via constructor.
 This is because the life cycles of these properties differ from the life cycle of objects managed directly by Spring.
 
 This is obviously only an issue if you want to inject EntityId or EventSourcedEntityCreationContext.
 Otherwise, if you want to inject only other Spring Context Beans, you can use injection via builders as normal.
 
 The builders below would be perfectly acceptable:
 
-```java
+[source,java]
+----
 @EventSourcedEntity
 @CloudstateEntityBean
 public final class ShoppingCartEntity {
@@ -58,19 +55,19 @@ public final class ShoppingCartEntity {
     private final RuleService ruleService;
 
     private final ShoppingCartTypeConverter typeConverter;
-    
+
     @Autowired
     public ShoppingCartEntity(RuleService ruleService, ShoppingCartTypeConverter typeConverter){
         this.ruleService = ruleService;
         this.typeConverter = typeConverter;
     }
-    
+
     //......
 }
-```
-@@@ note { title=Important }
-
-As you can see, the constructor injection constraint applies only to EntityId and CreationContext. 
-So, as in the example above, you can mix the approaches and get the best of both worlds together 
+----
 
-@@@
+[IMPORTANT]
+====
+As you can see, the constructor injection constraint applies only to EntityId and CreationContext.
+So, as in the example above, you can mix the approaches and get the best of both worlds together
+====