Convert docs to asciidoc/antora

.travis.yml

@@ -14,16 +14,12 @@ jobs:
       after_success:
         - if [ "$TRAVIS_OS_NAME" = "linux" ]; then bash <(curl -s https://codecov.io/bash); fi
 
+    - stage: validate docs
+      script: make -C docs
+
     - stage: deploy docs
-      name: deploy release docs to cloudstate.io
       if: tag =~ ^v
-      language: scala
-      script: cd docs && sbt deploy
-    - stage: deploy docs
-      name: deploy snapshot docs to cloudstate.io
-      if: branch = master AND type = push
-      language: scala
-      script: cd docs && sbt deploy
+      script: make -C docs deploy
 
 env:
   global:

cloudstate/event.go

@@ -86,30 +86,30 @@ func (e *eventEmitter) Clear() {
 	e.events = make([]interface{}, 0)
 }
 
-//#event-handler
+// tag::event-handler[]
 type EventHandler interface {
 	HandleEvent(ctx context.Context, event interface{}) (handled bool, err error)
 }
 
-//#event-handler
+// end::event-handler[]
 
-//#command-handler
+// tag::command-handler[]
 type CommandHandler interface {
 	HandleCommand(ctx context.Context, command interface{}) (handled bool, reply interface{}, err error)
 }
 
-//#command-handler
+// end::command-handler[]
 
-//#snapshotter
+// tag::snapshotter[]
 type Snapshotter interface {
 	Snapshot() (snapshot interface{}, err error)
 }
 
-//#snapshotter
+// end::snapshotter[]
 
-//#snapshot-handler
+// tag::snapshot-handler[]
 type SnapshotHandler interface {
 	HandleSnapshot(snapshot interface{}) (handled bool, err error)
 }
 
-//#snapshot-handler
+// end::snapshot-handler[]

cloudstate/eventsourced.go

@@ -40,7 +40,7 @@ const snapshotEveryDefault = 100
 
 // EventSourcedEntity captures an Entity, its ServiceName and PersistenceID.
 // It is used to be registered as an event sourced entity on a CloudState instance.
-//#event-sourced-entity-type
+// tag::event-sourced-entity-type[]
 type EventSourcedEntity struct {
 	// ServiceName is the fully qualified name of the service that implements this entities interface.
 	// Setting it is mandatory.
@@ -59,15 +59,15 @@ type EventSourcedEntity struct {
 	SnapshotEvery int64
 
 	// EntityFactory is a factory method which generates a new Entity.
-	//#event-sourced-entity-func
+	// tag::event-sourced-entity-func[]
 	EntityFunc func() Entity
-	//#event-sourced-entity-func
+	// end::event-sourced-entity-func[]
 
 	// internal
 	registerOnce sync.Once
 }
 
-//#event-sourced-entity-type
+// end::event-sourced-entity-type[]
 
 // init get its Entity type and Zero-Value it to
 // something we can use as an initializer.

docs/.gitignore

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

docs/Makefile

@@ -0,0 +1,71 @@
+# Make Cloudstate Go documentation
+
+module   := go
+upstream := cloudstateio/go-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
+root_dir := $(shell git rev-parse --show-toplevel)
+src_managed := build/src/managed
+managed_examples := ${src_managed}/modules/go/examples
+managed_partials := ${src_managed}/modules/go/partials
+
+define copy_example
+	mkdir -p "${managed_examples}/$$(dirname $1)"
+	cp "${root_dir}/$1" "${managed_examples}/$1"
+endef
+
+.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 examples
+	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-go-lib-version: %s" \
+		> "${managed_partials}/attributes.adoc"
+
+examples:
+	# also create empty go module to ignore example sources
+	mkdir -p "${managed_examples}"
+	touch "${managed_examples}/go.mod"
+	$(call copy_example,cloudstate/event.go)
+	$(call copy_example,cloudstate/eventsourced.go)
+	$(call copy_example,protobuf/example/shoppingcart/persistence/domain.proto)
+	$(call copy_example,tck/cmd/tck_shoppingcart/shoppingcart.go)
+
+${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
+
+deploy: clean managed
+	${cloudstate_antora} deploy --module ${module} --upstream ${upstream} --branch ${branch} ${sources}

docs/README.md

@@ -1,23 +1,19 @@
 # Cloudstate Go documentation
 
-Documentation source for Cloudstate Go, published to https://cloudstate.io/docs/go/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`.
 
-```
-sbt paradox
-```
-
-Can also first start the sbt interactive shell with `sbt`, then run commands.
-
-The documentation can be viewed locally by opening the generated pages:
+To build the documentation run:
 
 ```
-open target/paradox/site/main/index.html
+make
 ```
 
-To watch files for changes and rebuild docs automatically:
+The generated documentation site will be available in the `build/site` directory:
 
 ```
-sbt ~paradox
+open build/site/index.html
 ```
+
+Documentation will be automatically deployed on tagged versions, in the Travis CI builds.

docs/src/antora.yml

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