diff --git a/cloudbuild/main.yaml b/cloudbuild/main.yaml index 34f1876e..ff654a35 100644 --- a/cloudbuild/main.yaml +++ b/cloudbuild/main.yaml @@ -44,6 +44,15 @@ steps: "gs://kosu-docs/kosu-system-contracts" ] +- name: "gcr.io/cloud-builders/gsutil" + args: [ + "-m", + "rsync", + "-r", "-c", "-d", + "./packages/go-kosu/docs", + "gs://kosu-docs/go-kosu" + ] + # ================ # PUBLISH BINARIES # ================ @@ -86,6 +95,15 @@ steps: "./packages/kosu-docs/docs/kosu-system-contracts" ] +- name: "gcr.io/cloud-builders/gsutil" + args: [ + "-m", + "rsync", + "-r", "-c", "-d", + "./packages/go-kosu/docs", + "./packages/kosu-docs/docs/go-kosu" + ] + - name: "gcr.io/kosu-io/node-ci:latest" entrypoint: "yarn" args: [ diff --git a/packages/go-kosu/.golangci.yml b/packages/go-kosu/.golangci.yml new file mode 100644 index 00000000..ce72df7d --- /dev/null +++ b/packages/go-kosu/.golangci.yml @@ -0,0 +1,5 @@ +issues: + exclude-rules: + - path: rpc/service.go + linters: + - lll diff --git a/packages/go-kosu/Makefile b/packages/go-kosu/Makefile index aa514b38..500036a4 100644 --- a/packages/go-kosu/Makefile +++ b/packages/go-kosu/Makefile @@ -32,3 +32,6 @@ gen: go generate ./... ci: lint test + +rpcdocs: + cd ./rpc/doctool && go run main.go ../ diff --git a/packages/go-kosu/package.json b/packages/go-kosu/package.json index 9afa8889..d7499ecf 100644 --- a/packages/go-kosu/package.json +++ b/packages/go-kosu/package.json @@ -7,10 +7,14 @@ "license": "MIT", "scripts": { "build": "yarn abigen && make", - "abigen": "jq '.compilerOutput.abi' node_modules/@kosu/system-contracts/generated-artifacts/EventEmitter.json | abigen --abi - --pkg witness --type EventEmitter -out witness/event_emitter.go" + "abigen": "jq '.compilerOutput.abi' node_modules/@kosu/system-contracts/generated-artifacts/EventEmitter.json | abigen --abi - --pkg witness --type EventEmitter -out witness/event_emitter.go", + "docs": "yarn docs:clean && yarn docs:setup && yarn docs:rpc", + "docs:clean": "rm -rf ./docs/", + "docs:setup": "mkdir -p ./docs && cp README.md ./docs/", + "docs:rpc": "make -s rpcdocs > docs/kosu_rpc.md" }, "config": {}, "dependencies": { - "@kosu/system-contracts": "^0.1.1" + "@kosu/system-contracts": "^0.1.5" } } diff --git a/packages/go-kosu/rpc/doctool/main.go b/packages/go-kosu/rpc/doctool/main.go index b1a68e7c..06e959c1 100644 --- a/packages/go-kosu/rpc/doctool/main.go +++ b/packages/go-kosu/rpc/doctool/main.go @@ -1,21 +1,35 @@ package main import ( - "encoding/json" "fmt" "go/doc" "go/parser" "go/token" "log" "os" + "text/template" ) -// nolint +// DocEntry holds documentation for a method type DocEntry struct { Method string `json:"method"` Text string `json:"text"` } +// TypeDocs holds the documentation of a given type +type TypeDocs struct { + Title string + Description string + Entries []DocEntry +} + +// PkgDocs is the top level doc struct +type PkgDocs struct { + Title string + Description string + Types []TypeDocs +} + func main() { if len(os.Args) < 2 { fmt.Println("Usage: doctool ") @@ -28,18 +42,28 @@ func main() { log.Fatal(err) } - docs := []DocEntry{} pkg := doc.New(pkgs["rpc"], os.Args[1], doc.AllDecls) + pkgDocs := PkgDocs{ + Title: pkg.Name, + Description: pkg.Doc, + } for _, t := range pkg.Types { + if t.Name != "Service" { + continue + } + typeDocs := TypeDocs{Title: t.Name, Description: t.Doc} for _, m := range t.Methods { - docs = append(docs, DocEntry{Method: m.Name, Text: m.Doc}) + typeDocs.Entries = append(typeDocs.Entries, DocEntry{Method: m.Name, Text: m.Doc}) } + pkgDocs.Types = append(pkgDocs.Types, typeDocs) } - text, err := json.MarshalIndent(docs, "", " ") + t, err := template.New("template.md.tpl").ParseFiles("./template.md.tpl") if err != nil { - log.Fatal(err) + panic(err) + } + if err := t.Execute(os.Stdout, pkgDocs); err != nil { + panic(err) } - fmt.Printf("%s\n", text) } diff --git a/packages/go-kosu/rpc/doctool/template.md.tpl b/packages/go-kosu/rpc/doctool/template.md.tpl new file mode 100644 index 00000000..659032ee --- /dev/null +++ b/packages/go-kosu/rpc/doctool/template.md.tpl @@ -0,0 +1,14 @@ +--- +title: Methods +--- + +{{ .Description }} + +{{- range .Types }} +{{- range .Entries }} + +## Method: {{ .Method }} + +{{ .Text }} +{{ end }} +{{ end }} diff --git a/packages/go-kosu/rpc/rpc_test.go b/packages/go-kosu/rpc/rpc_test.go index 7fe6f97f..c27a8b08 100644 --- a/packages/go-kosu/rpc/rpc_test.go +++ b/packages/go-kosu/rpc/rpc_test.go @@ -15,14 +15,19 @@ import ( "github.com/tendermint/tendermint/libs/db" ) -func TestRPCLatestHeight(t *testing.T) { - _, closer := tests.StartServer(t, db.NewMemDB()) - defer closer() +func setupNewTestClient(t *testing.T) (*abci.App, *rpc.Client, func()) { + app, closer := tests.StartServer(t, db.NewMemDB()) client := rpc.DialInProc( NewServer( abci.NewHTTPClient("http://localhost:26657", nil), ), ) + return app, client, closer +} + +func TestRPCLatestHeight(t *testing.T) { + _, client, closer := setupNewTestClient(t) + defer closer() var latest uint64 // Get the initial (prior the first block is mined) @@ -34,6 +39,7 @@ func TestRPCLatestHeight(t *testing.T) { // this is invoked when a block is mined require.NoError(t, client.Call(&latest, "kosu_latestHeight")) assert.EqualValues(t, 1, latest) + cancel() } diff --git a/packages/go-kosu/rpc/service.go b/packages/go-kosu/rpc/service.go index feeb9012..f1c0f3f9 100644 --- a/packages/go-kosu/rpc/service.go +++ b/packages/go-kosu/rpc/service.go @@ -22,9 +22,44 @@ func NewService(abci *abci.Client) *Service { } } -// Subscribe subscribes to the ABCI events -// To tell which events you want, you need to provide a query. -// More information about query can be found here: https://tendermint.com/rpc/#subscribe +/* +Subscribe subscribes to the ABCI events. + +To tell which events you want, you need to provide a query. +More information about query can be found here: https://tendermint.com/rpc/#subscribe +Subscriptions will only work over WS. +#### Parameters +`query` TM query string + +#### Returns +`*rpc.Subscription` + +#### Examples +```go +ch := make(chan interface{}) +args := []interface{}{ + "subscribe", + "tm.event='NewBlock'", +} +ctx := context.Background() +sub, err := client.Subscribe(ctx, "kosu", ch, args...) +if err != nil { + panic(err) +} +defer sub.Unsubscribe() + +for { + select { + case <-ctx.Done(): + return + case <-sub.Err(): + return + case e := <-ch: + fmt.Printf("event: %+v", e) + } +} +``` +*/ func (s *Service) Subscribe(ctx context.Context, query string) (*rpc.Subscription, error) { notifier, supported := rpc.NotifierFromContext(ctx) if !supported { @@ -58,8 +93,22 @@ func (s *Service) Subscribe(ctx context.Context, query string) (*rpc.Subscriptio return rpcSub, nil } -// LatestHeight returns the height of the best known block -// The `latestHeight` method will return the integer height of the latest block committed to the blockchain.", +/* +LatestHeight returns the height of the best known block. +The `latestHeight` method will return the integer height of the latest block committed to the blockchain. + +#### Parameters +None + +#### Returns +`latestHeight` - _int64_ latest block height + +#### Examples +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"kosu_latestHeight", "id": 1}' localhost:14341 --header 'Content-Type: application/json' +{"jsonrpc":"2.0","id":1,"result":260} +``` +*/ func (s *Service) LatestHeight() (int64, error) { res, err := s.abci.Block(nil) if err != nil { @@ -74,7 +123,7 @@ func (s *Service) LatestHeight() (int64, error) { // AddOrders adds an array of Kosu orders to the network /* -*** Example payload +### Example payload ```json [{ "subContract":"0xebe8fdf63db77e3b41b0aec8208c49fa46569606", @@ -106,14 +155,13 @@ func (s *Service) LatestHeight() (int64, error) { }]`, ``` -*** cURL example +### cURL example ```bash -url -X POST localhost:14341 \ +curl -X POST localhost:14341 \ --data '{"jsonrpc":"2.0", "id": 1, "method": "kosu_addOrders", "params": [[]]}' \ -H 'Content-Type: application/json' ``` */ -// nolint:lll func (s *Service) AddOrders(orders []*types.TransactionOrder) error { for _, order := range orders { res, err := s.abci.BroadcastTxSync(order) diff --git a/packages/kosu-docs/docs/.vuepress/config.js b/packages/kosu-docs/docs/.vuepress/config.js index 576dbe70..d92a4df5 100644 --- a/packages/kosu-docs/docs/.vuepress/config.js +++ b/packages/kosu-docs/docs/.vuepress/config.js @@ -78,6 +78,12 @@ module.exports = { "/kosu-system-contracts/Voting", ], }, + { + title: "Go Kosu", + collapsable: true, + food: "4.svg", + children: ["/go-kosu/", "/go-kosu/kosu_rpc"], + }, ], }, }; diff --git a/packages/kosu-docs/load.sh b/packages/kosu-docs/load.sh index 03985c32..debee099 100755 --- a/packages/kosu-docs/load.sh +++ b/packages/kosu-docs/load.sh @@ -38,6 +38,7 @@ log "$LOADING_DOCS" gsutil -m rsync -r -c -d gs://kosu-docs/kosu.js ./docs/kosu.js gsutil -m rsync -r -c -d gs://kosu-docs/kosu-system-contracts ./docs/kosu-system-contracts +gsutil -m rsync -r -c -d gs://kosu-docs/go-kosu ./docs/go-kosu log "$LOADED_DOCS" exit 0 \ No newline at end of file