From 7f20eb5f8ecdb5528d9aee8e3549880229ac73b8 Mon Sep 17 00:00:00 2001 From: Zach Date: Fri, 25 May 2018 07:59:24 -0400 Subject: [PATCH] generate RPC docs using Slate (#1612) * generate RPC docs using Slate (#691) * update changelog * skip if branch not develop * slate: only build if rpc/core has changes * fetch develop to compare against * slate: build on master only * [rpc/core] use original repo, not fork in README --- .circleci/config.yml | 19 ++++ CHANGELOG.md | 4 +- Makefile | 7 +- docs/specification/rpc.rst | 188 +------------------------------------ rpc/core/README.md | 9 +- rpc/core/doc.go | 2 +- scripts/slate.sh | 77 +++++++++++++++ 7 files changed, 110 insertions(+), 196 deletions(-) create mode 100644 scripts/slate.sh diff --git a/.circleci/config.yml b/.circleci/config.yml index 177c1458f..4209d531e 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -77,6 +77,22 @@ jobs: paths: - "bin/abci*" + build_slate: + <<: *defaults + steps: + - attach_workspace: + at: /tmp/workspace + - restore_cache: + key: v1-pkg-cache + - restore_cache: + key: v1-tree-{{ .Environment.CIRCLE_SHA1 }} + - run: + name: slate docs + command: | + set -ex + export PATH="$GOBIN:$PATH" + make build-slate + lint: <<: *defaults steps: @@ -180,6 +196,9 @@ workflows: test-suite: jobs: - setup_dependencies + - build_slate: + requires: + - setup_dependencies - setup_abci: requires: - setup_dependencies diff --git a/CHANGELOG.md b/CHANGELOG.md index bf3059374..bde5b2e40 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,9 @@ ## 0.19.6 -*TBD* +FEATURES + +- [rpc] the RPC documentation is now published to https://tendermint.github.io/slate IMPROVEMENTS: diff --git a/Makefile b/Makefile index 991bfb263..079c58f90 100755 --- a/Makefile +++ b/Makefile @@ -226,8 +226,11 @@ sentry-stop: @if [ -z "$(DO_API_TOKEN)" ]; then echo "DO_API_TOKEN environment variable not set." ; false ; fi cd networks/remote/terraform && terraform destroy -var DO_API_TOKEN="$(DO_API_TOKEN)" -var SSH_KEY_FILE="$(HOME)/.ssh/id_rsa.pub" +# meant for the CI, inspect script & adapt accordingly +build-slate: + bash scripts/slate.sh + # To avoid unintended conflicts with file names, always add to .PHONY # unless there is a reason not to. # https://www.gnu.org/software/make/manual/html_node/Phony-Targets.html -.PHONY: check build build_race dist install check_tools get_tools update_tools get_vendor_deps draw_deps test_cover test_apps test_persistence test_p2p test test_race test_integrations test_release test100 vagrant_test fmt build-linux localnet-start localnet-stop build-docker build-docker-localnode sentry-start sentry-config sentry-stop - +.PHONY: check build build_race dist install check_tools get_tools update_tools get_vendor_deps draw_deps test_cover test_apps test_persistence test_p2p test test_race test_integrations test_release test100 vagrant_test fmt build-linux localnet-start localnet-stop build-docker build-docker-localnode sentry-start sentry-config sentry-stop build-slate diff --git a/docs/specification/rpc.rst b/docs/specification/rpc.rst index 386791aa7..1dd1165b9 100644 --- a/docs/specification/rpc.rst +++ b/docs/specification/rpc.rst @@ -1,190 +1,4 @@ RPC === -Coming soon: RPC docs powered by `slate `__. Until then, read on. - -Tendermint supports the following RPC protocols: - -- URI over HTTP -- JSONRPC over HTTP -- JSONRPC over websockets - -Tendermint RPC is build using `our own RPC -library `__. -Documentation and tests for that library could be found at -``tendermint/rpc/lib`` directory. - -Configuration -~~~~~~~~~~~~~ - -Set the ``laddr`` config parameter under ``[rpc]`` table in the -$TMHOME/config/config.toml file or the ``--rpc.laddr`` command-line flag to the -desired protocol://host:port setting. Default: ``tcp://0.0.0.0:46657``. - -Arguments -~~~~~~~~~ - -Arguments which expect strings or byte arrays may be passed as quoted -strings, like ``"abc"`` or as ``0x``-prefixed strings, like -``0x616263``. - -URI/HTTP -~~~~~~~~ - -Example request: - -.. code:: bash - - curl -s 'http://localhost:46657/broadcast_tx_sync?tx="abc"' | jq . - -Response: - -.. code:: json - - { - "error": "", - "result": { - "hash": "2B8EC32BA2579B3B8606E42C06DE2F7AFA2556EF", - "log": "", - "data": "", - "code": 0 - }, - "id": "", - "jsonrpc": "2.0" - } - -The first entry in the result-array (``96``) is the method this response -correlates with. ``96`` refers to "ResultTypeBroadcastTx", see -`responses.go `__ -for a complete overview. - -JSONRPC/HTTP -~~~~~~~~~~~~ - -JSONRPC requests can be POST'd to the root RPC endpoint via HTTP (e.g. -``http://localhost:46657/``). - -Example request: - -.. code:: json - - { - "method": "broadcast_tx_sync", - "jsonrpc": "2.0", - "params": [ "abc" ], - "id": "dontcare" - } - -JSONRPC/websockets -~~~~~~~~~~~~~~~~~~ - -JSONRPC requests can be made via websocket. The websocket endpoint is at -``/websocket``, e.g. ``http://localhost:46657/websocket``. Asynchronous -RPC functions like event ``subscribe`` and ``unsubscribe`` are only -available via websockets. - -Endpoints -~~~~~~~~~ - -An HTTP Get request to the root RPC endpoint (e.g. -``http://localhost:46657``) shows a list of available endpoints. - -:: - - Available endpoints: - http://localhost:46657/abci_info - http://localhost:46657/dump_consensus_state - http://localhost:46657/genesis - http://localhost:46657/net_info - http://localhost:46657/num_unconfirmed_txs - http://localhost:46657/health - http://localhost:46657/status - http://localhost:46657/unconfirmed_txs - http://localhost:46657/unsafe_flush_mempool - http://localhost:46657/unsafe_stop_cpu_profiler - http://localhost:46657/validators - - Endpoints that require arguments: - http://localhost:46657/abci_query?path=_&data=_&prove=_ - http://localhost:46657/block?height=_ - http://localhost:46657/blockchain?minHeight=_&maxHeight=_ - http://localhost:46657/broadcast_tx_async?tx=_ - http://localhost:46657/broadcast_tx_commit?tx=_ - http://localhost:46657/broadcast_tx_sync?tx=_ - http://localhost:46657/commit?height=_ - http://localhost:46657/dial_seeds?seeds=_ - http://localhost:46657/dial_peers?peers=_&persistent=_ - http://localhost:46657/subscribe?event=_ - http://localhost:46657/tx?hash=_&prove=_ - http://localhost:46657/unsafe_start_cpu_profiler?filename=_ - http://localhost:46657/unsafe_write_heap_profile?filename=_ - http://localhost:46657/unsubscribe?event=_ - -tx -~~ - -Returns a transaction matching the given transaction hash. - -**Parameters** - -1. hash - the transaction hash -2. prove - include a proof of the transaction inclusion in the block in - the result (optional, default: false) - -**Returns** - -- ``proof``: the ``types.TxProof`` object -- ``tx``: ``[]byte`` - the transaction -- ``tx_result``: the ``abci.Result`` object -- ``index``: ``int`` - index of the transaction -- ``height``: ``int`` - height of the block where this transaction was - in - -**Example** - -.. code:: bash - - curl -s 'http://localhost:46657/broadcast_tx_commit?tx="abc"' | jq . - # { - # "error": "", - # "result": { - # "hash": "2B8EC32BA2579B3B8606E42C06DE2F7AFA2556EF", - # "log": "", - # "data": "", - # "code": 0 - # }, - # "id": "", - # "jsonrpc": "2.0" - # } - - curl -s 'http://localhost:46657/tx?hash=0x2B8EC32BA2579B3B8606E42C06DE2F7AFA2556EF' | jq . - # { - # "error": "", - # "result": { - # "proof": { - # "Proof": { - # "aunts": [] - # }, - # "Data": "YWJjZA==", - # "RootHash": "2B8EC32BA2579B3B8606E42C06DE2F7AFA2556EF", - # "Total": 1, - # "Index": 0 - # }, - # "tx": "YWJjZA==", - # "tx_result": { - # "log": "", - # "data": "", - # "code": 0 - # }, - # "index": 0, - # "height": 52 - # }, - # "id": "", - # "jsonrpc": "2.0" - # } - -More Examples -~~~~~~~~~~~~~ - -See the various bash tests using curl in ``test/``, and examples using -the ``Go`` API in ``rpc/client/``. +The RPC documentation is hosted `here `__ and is generated by the CI from our `Slate repo `__. To update the documentation, edit the relevant ``godoc`` comments in the `rpc/core directory `__. diff --git a/rpc/core/README.md b/rpc/core/README.md index df84d6e64..9547079b2 100644 --- a/rpc/core/README.md +++ b/rpc/core/README.md @@ -3,17 +3,16 @@ ## Generate markdown for [Slate](https://github.com/tendermint/slate) We are using [Slate](https://github.com/tendermint/slate) to power our RPC -documentation. If you are changing a comment, make sure to copy the resulting -changes to the slate repo and make a PR -[there](https://github.com/tendermint/slate) as well. For generating markdown -use: +documentation. For generating markdown use: ```shell -go get github.com/melekes/godoc2md +go get github.com/davecheney/godoc2md godoc2md -template rpc/core/doc_template.txt github.com/tendermint/tendermint/rpc/core | grep -v -e "pipe.go" -e "routes.go" -e "dev.go" | sed 's$/src/target$https://github.com/tendermint/tendermint/tree/master/rpc/core$' ``` +For more information see the [CI script for building the Slate docs](/scripts/slate.sh) + ## Pagination Requests that return multiple items will be paginated to 30 items by default. diff --git a/rpc/core/doc.go b/rpc/core/doc.go index b479482c4..d18cda6ac 100644 --- a/rpc/core/doc.go +++ b/rpc/core/doc.go @@ -7,7 +7,7 @@ Tendermint supports the following RPC protocols: * JSONRPC over HTTP * JSONRPC over websockets -Tendermint RPC is built using [our own RPC library](https://github.com/tendermint/tendermint/tree/master/rpc/lib). Documentation and tests for that library could be found at `tendermint/rpc/lib` directory. +Tendermint RPC is built using [our own RPC library](https://github.com/tendermint/tendermint/tree/master/rpc/lib) which contains its own set of documentation and tests. ## Configuration diff --git a/scripts/slate.sh b/scripts/slate.sh new file mode 100644 index 000000000..e18babea7 --- /dev/null +++ b/scripts/slate.sh @@ -0,0 +1,77 @@ +#!/usr/bin/env bash +set -euo pipefail + +if [ "$CIRCLE_BRANCH" == "" ]; then + echo "this script is meant to be run on CircleCI, exiting" + echo 1 +fi + +# check for changes in the `rpc/core` directory +did_rpc_change=$(git diff --name-status $CIRCLE_BRANCH origin/master | grep rpc/core) + +if [ "$did_rpc_change" == "" ]; then + echo "no changes detected in rpc/core, exiting" + exit 0 +else + echo "changes detected in rpc/core, continuing" +fi + +# only run this script on changes to rpc/core committed to develop +if [ "$CIRCLE_BRANCH" != "master" ]; then + echo "the branch being built isn't master, exiting" + exit 0 +else + echo "on master, building the RPC docs" +fi + +# godoc2md used to convert the go documentation from +# `rpc/core` into a markdown file consumed by Slate +go get github.com/davecheney/godoc2md + +# slate works via forks, and we'll be committing to +# master branch, which will trigger our fork to run +# the `./deploy.sh` and publish via the `gh-pages` branch +slate_repo=github.com/tendermint/slate +slate_path="$GOPATH"/src/"$slate_repo" + +if [ ! -d "$slate_path" ]; then + git clone https://"$slate_repo".git $slate_path +fi + +# the main file we need to update if rpc/core changed +destination="$slate_path"/source/index.html.md + +# we remove it then re-create it with the latest changes +rm $destination + +header="--- +title: RPC Reference + +language_tabs: + - shell + - go + +toc_footers: + - Tendermint + - Documentation Powered by Slate + +search: true +---" + +# write header to the main slate file +echo "$header" > "$destination" + +# generate a markdown from the godoc comments, using a template +rpc_docs=$(godoc2md -template rpc/core/doc_template.txt github.com/tendermint/tendermint/rpc/core | grep -v -e "pipe.go" -e "routes.go" -e "dev.go" | sed 's$/src/target$https://github.com/tendermint/tendermint/tree/master/rpc/core$') + +# append core RPC docs +echo "$rpc_docs" >> "$destination" + +# commit the changes +cd $slate_path + +git config --global user.email "github@tendermint.com" +git config --global user.name "tenderbot" + +git commit -a -m "Update tendermint RPC docs via CircleCI" +git push -q https://${GITHUB_ACCESS_TOKEN}@github.com/tendermint/slate.git master