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
This commit is contained in:
parent
eeabb4c06b
commit
7f20eb5f8e
|
@ -77,6 +77,22 @@ jobs:
|
||||||
paths:
|
paths:
|
||||||
- "bin/abci*"
|
- "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:
|
lint:
|
||||||
<<: *defaults
|
<<: *defaults
|
||||||
steps:
|
steps:
|
||||||
|
@ -180,6 +196,9 @@ workflows:
|
||||||
test-suite:
|
test-suite:
|
||||||
jobs:
|
jobs:
|
||||||
- setup_dependencies
|
- setup_dependencies
|
||||||
|
- build_slate:
|
||||||
|
requires:
|
||||||
|
- setup_dependencies
|
||||||
- setup_abci:
|
- setup_abci:
|
||||||
requires:
|
requires:
|
||||||
- setup_dependencies
|
- setup_dependencies
|
||||||
|
|
|
@ -2,7 +2,9 @@
|
||||||
|
|
||||||
## 0.19.6
|
## 0.19.6
|
||||||
|
|
||||||
*TBD*
|
FEATURES
|
||||||
|
|
||||||
|
- [rpc] the RPC documentation is now published to https://tendermint.github.io/slate
|
||||||
|
|
||||||
IMPROVEMENTS:
|
IMPROVEMENTS:
|
||||||
|
|
||||||
|
|
7
Makefile
7
Makefile
|
@ -226,8 +226,11 @@ sentry-stop:
|
||||||
@if [ -z "$(DO_API_TOKEN)" ]; then echo "DO_API_TOKEN environment variable not set." ; false ; fi
|
@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"
|
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
|
# To avoid unintended conflicts with file names, always add to .PHONY
|
||||||
# unless there is a reason not to.
|
# unless there is a reason not to.
|
||||||
# https://www.gnu.org/software/make/manual/html_node/Phony-Targets.html
|
# 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
|
||||||
|
|
||||||
|
|
|
@ -1,190 +1,4 @@
|
||||||
RPC
|
RPC
|
||||||
===
|
===
|
||||||
|
|
||||||
Coming soon: RPC docs powered by `slate <https://github.com/lord/slate>`__. Until then, read on.
|
The RPC documentation is hosted `here <https://tendermint.github.io/slate>`__ and is generated by the CI from our `Slate repo <https://github.com/tendermint/slate>`__. To update the documentation, edit the relevant ``godoc`` comments in the `rpc/core directory <https://github.com/tendermint/tendermint/tree/develop/rpc/core>`__.
|
||||||
|
|
||||||
Tendermint supports the following RPC protocols:
|
|
||||||
|
|
||||||
- URI over HTTP
|
|
||||||
- JSONRPC over HTTP
|
|
||||||
- JSONRPC over websockets
|
|
||||||
|
|
||||||
Tendermint RPC is build 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.
|
|
||||||
|
|
||||||
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 <https://github.com/tendermint/tendermint/blob/master/rpc/core/types/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/``.
|
|
||||||
|
|
|
@ -3,17 +3,16 @@
|
||||||
## Generate markdown for [Slate](https://github.com/tendermint/slate)
|
## Generate markdown for [Slate](https://github.com/tendermint/slate)
|
||||||
|
|
||||||
We are using [Slate](https://github.com/tendermint/slate) to power our RPC
|
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
|
documentation. For generating markdown use:
|
||||||
changes to the slate repo and make a PR
|
|
||||||
[there](https://github.com/tendermint/slate) as well. For generating markdown
|
|
||||||
use:
|
|
||||||
|
|
||||||
```shell
|
```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$'
|
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
|
## Pagination
|
||||||
|
|
||||||
Requests that return multiple items will be paginated to 30 items by default.
|
Requests that return multiple items will be paginated to 30 items by default.
|
||||||
|
|
|
@ -7,7 +7,7 @@ Tendermint supports the following RPC protocols:
|
||||||
* JSONRPC over HTTP
|
* JSONRPC over HTTP
|
||||||
* JSONRPC over websockets
|
* 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
|
## Configuration
|
||||||
|
|
||||||
|
|
|
@ -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:
|
||||||
|
- <a href='https://tendermint.com/'>Tendermint</a>
|
||||||
|
- <a href='https://github.com/lord/slate'>Documentation Powered by Slate</a>
|
||||||
|
|
||||||
|
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
|
Loading…
Reference in New Issue