Doc: move rpc_usage to tutorials/rpc

docs/Makefile

@@ -24,8 +24,8 @@ api/errors.rst: $(DOCERRORDIR)/error_doc.ml
 $(DOCGENDIR)/rpc_doc.exe:
 	@cd .. && dune build docs/$(DOCGENDIR)/rpc_doc.exe
 
-api/rpc.rst: $(DOCGENDIR)/rpc_doc.exe api/rpc_usage.rst.inc
+api/rpc.rst: $(DOCGENDIR)/rpc_doc.exe
-	@dune exec $(DOCGENDIR)/rpc_doc.exe < api/rpc_usage.rst.inc > api/rpc.rst
+	@dune exec $(DOCGENDIR)/rpc_doc.exe > api/rpc.rst
 
 $(DOCGENDIR)/p2p_doc.exe:
 	@cd .. && dune build docs/$(DOCGENDIR)/p2p_doc.exe

docs/api/rpc_usage.rst.inc

@@ -1,33 +0,0 @@
-This document contains the list of RPC services provided by the Tezos
-node. It is generated from the OCaml source code (master branch).
-
-The changes made in June 2018 for pre-Betanet are recapitulated in
-:ref:`this page<rpc_changes_june_2018>`.
-
-Usage
-*****
-
-In order to interact with a Tezos node, you may use RPC calls through the
-client using this command ``tezos-admin-client rpc (get|post) <url>``.
-
-For instance, if you wish to request the current balance of a given
-block and contract, you can call the associated RPC via the command :
-``$ tezos-admin-client rpc get
-/blocks/<block_id>/proto/context/contracts/<contract_id>/balance``.
-
-A RPC may takes an *input* and generates an *output* both in JSON
-format. For example, the previous RPC call, that does not require an
-input, would display on the standard output : ``{ "balance":
-"4000000000000" }``. When calling a RPC that requires an input
-through command-line, you will be prompted to provide the JSON input
-in your default configured text editor. Alternatively, you can provide
-the JSON input using command
-``$ tezos-admin-client rpc post <url> with <JSON>``. Don't forget to quote
-the JSON according to your shell rules.
-
-You can also obtain the list of RPCs on the command line with
-``tezos-admin-client rpc list /``, and the description of each service
-using ``tezos-admin-client rpc format <url>``.
-
-Of course, you can use your standard HTTP tool or library as well to
-perform all these tasks.

docs/doc_gen/rpc_doc.ml

@@ -267,18 +267,10 @@ let pp_document ppf descriptions =
   Format.fprintf ppf "%a@." Rst.pp_raw_html Rst.style ;
   (* Script : hack *)
   Format.fprintf ppf "%a@." Rst.pp_raw_html Rst.script ;
-  (* Page title *)
-  Format.fprintf ppf "%a" Rst.pp_h1 "RPC API" ;
-  (* include/copy usage.rst from input  *)
-  let rec loop () =
-    let s = read_line () in
-    Format.fprintf ppf "%s@\n" s ;
-    loop () in
-  begin try loop () with End_of_file -> () end ;
-  Format.fprintf ppf "@\n" ;
   (* Index *)
   Format.pp_set_margin ppf 10000 ;
   Format.pp_set_max_indent ppf 9000 ;
+  Format.fprintf ppf "%a" Rst.pp_ref "rpc_index" ;
   Rst.pp_h2 ppf "RPCs - Index" ;
   List.iter
     (fun (name, prefix, rpc_dir) ->

docs/tutorials/rpc.rst

@@ -0,0 +1,76 @@
+.. _rpc:
+
+
+JSON/RPC interface
+==================
+
+The Tezos node provides a JSON/RPC interface. Note that it is an RPC,
+and it is JSON based, but it does not follow the “JSON-RPC” protocol. It
+is not active by default and it must be explicitly activated with the
+``--rpc-addr`` option. Typically, if you are not trying to run a local
+network and just want to explore the RPC, you would run:
+
+::
+
+    ./tezos-node run --rpc-addr localhost
+
+The RPC interface is self-documented and the ``tezos-client`` executable
+is able to pretty-print the RPC API. For instance, to see the API
+provided by the Tezos Shell:
+
+::
+
+    ./tezos-client rpc list
+
+To get API attached to the “genesis” block, including the remote
+procedures provided by the associated economic protocol version:
+
+::
+
+    ./tezos-client rpc list /blocks/genesis/
+
+You might also want the JSON schema describing the expected input and
+output of a RPC. For instance:
+
+::
+
+    ./tezos-client rpc schema /blocks/genesis/hash
+
+Note: you can get the same information, but as a raw JSON object, with a
+simple HTTP request:
+
+::
+
+   curl -s localhost:8732/chains/main/blocks/head~10
+   wget --post-data '{ "recursive": true }' -O - http://localhost:8732/describe
+   wget --post-data '{ "recursive": true }' -O - http://localhost:8732/describe/blocks/genesis
+   wget -O - http://localhost:8732/describe/blocks/genesis/hash
+
+
+An online :ref:`index <rpc_index>` of RPC calls is also available.
+The changes made in June 2018 for pre-Betanet are recapitulated in
+:ref:`this page<rpc_changes_june_2018>`.
+
+
+The general call of an RPC from the client is ``tezos-admin-client rpc
+(get|post) <url>``.
+For instance, if you wish to request the current balance of a given
+block and contract, you can call the associated RPC via the command :
+``$ tezos-admin-client rpc get
+/blocks/<block_id>/proto/context/contracts/<contract_id>/balance``.
+
+A RPC may take an *input* and generates an *output* both in JSON
+format. For example, the previous RPC call, that does not require an
+input, would display on the standard output : ``{ "balance":
+"4000000000000" }``. When calling a RPC that requires an input
+through command-line, you will be prompted to provide the JSON input
+in your default configured text editor. Alternatively, you can provide
+the JSON input using command
+``$ tezos-admin-client rpc post <url> with <JSON>``. Don't forget to quote
+the JSON according to your shell rules.
+
+If you want to learn more about the exchange of RPCs between node and
+client you can pass the option `-l` and the client will print all the
+calls with their input/output.
+
+A useful util to manipulate JSON is `jq <https://stedolan.github.io/jq/>`_.