Go kosu/rpc docs

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: [

packages/go-kosu/.golangci.yml

@@ -0,0 +1,5 @@
+issues:
+  exclude-rules:
+    - path: rpc/service.go
+      linters:
+        - lll

packages/go-kosu/Makefile

@@ -32,3 +32,6 @@ gen:
 	go generate ./...
 
 ci: lint test
+
+rpcdocs:
+	cd ./rpc/doctool && go run main.go ../

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"
     }
 }

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 <path>")
@@ -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)
 }

packages/go-kosu/rpc/doctool/template.md.tpl

@@ -0,0 +1,14 @@
+---
+title: Methods
+---
+
+{{ .Description }}
+
+{{- range .Types }}
+{{- range .Entries }}
+
+## Method: {{ .Method }}
+
+{{ .Text }}
+{{ end }}
+{{ end }}

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()
 	}
 

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": [[<PAYLOAD>]]}' \
 	-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)

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"],
+            },
         ],
     },
 };

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