Skip to content
This repository has been archived by the owner on Mar 11, 2022. It is now read-only.

Commit

Permalink
Merge pull request #39 from pvlugter/antora
Browse files Browse the repository at this point in the history
Convert docs to asciidoc/antora
  • Loading branch information
marcellanz authored Oct 1, 2020
2 parents d87dac5 + e9a3968 commit 4169acf
Show file tree
Hide file tree
Showing 25 changed files with 486 additions and 329 deletions.
12 changes: 4 additions & 8 deletions .travis.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
16 changes: 8 additions & 8 deletions cloudstate/event.go
Original file line number Diff line number Diff line change
Expand Up @@ -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[]
8 changes: 4 additions & 4 deletions cloudstate/eventsourced.go
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
Expand Down
3 changes: 3 additions & 0 deletions docs/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
/.cache/
/.deploy/
/build/
71 changes: 71 additions & 0 deletions docs/Makefile
Original file line number Diff line number Diff line change
@@ -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}
20 changes: 8 additions & 12 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -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.
12 changes: 0 additions & 12 deletions docs/build.sbt

This file was deleted.

1 change: 0 additions & 1 deletion docs/project/build.properties

This file was deleted.

2 changes: 0 additions & 2 deletions docs/project/plugins.sbt

This file was deleted.

2 changes: 2 additions & 0 deletions docs/src/antora.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
name: ""
version: master
3 changes: 0 additions & 3 deletions docs/src/main/paradox/api.md

This file was deleted.

118 changes: 0 additions & 118 deletions docs/src/main/paradox/eventsourced.md

This file was deleted.

Loading

0 comments on commit 4169acf

Please sign in to comment.