From 0863a2a9e4cc1a3bbd4d3af4838da0ce18361e78 Mon Sep 17 00:00:00 2001
From: Benjamin Canou <benjamin@canou.fr>
Date: Wed, 31 Jan 2018 12:23:03 +0100
Subject: [PATCH] Docs: add online help pages for the client

---
 .gitignore                        |  2 ++
 Makefile                          |  4 +++-
 README.rst                        |  8 ++++++--
 docs/api/cli-commands.rst         | 28 ++++++++++++++++++++++++++++
 docs/index.rst                    |  3 ++-
 src/lib_stdlib_lwt/cli_entries.ml |  8 ++++----
 6 files changed, 45 insertions(+), 8 deletions(-)
 create mode 100644 docs/api/cli-commands.rst

diff --git a/.gitignore b/.gitignore
index f73cc5a4a..98b70fa7c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,6 +8,8 @@ __pycache__
 /_opam
 /_docker_build
 /docs/_build
+/docs/api/tezos-client.html
+/docs/api/tezos-admin-client.html
 
 /tezos-node
 /tezos-protocol-compiler
diff --git a/Makefile b/Makefile
index 5bb6467b7..0b15f211d 100644
--- a/Makefile
+++ b/Makefile
@@ -16,8 +16,10 @@ tezos-%.pkg:
 	@jbuilder build --dev $(patsubst %.opam,%.install, \
 				   $(shell find -name tezos-$*.opam))
 
-doc-html:
+doc-html: all
 	@jbuilder build @doc ${DEV}
+	@./tezos-client -protocol ProtoALphaALph man -verbosity 3 -format html | sed "s/$HOME/\$HOME/g" > docs/api/tezos-client.html
+	@./tezos-admin-client man -verbosity 3 -format html | sed "s/$HOME/\$HOME/g" > docs/api/tezos-admin-client.html
 	@mkdir -p $$(pwd)/docs/_build/api/odoc
 	@rm -rf $$(pwd)/docs/_build/api/odoc/*
 	@cp -r $$(pwd)/_build/default/_doc/* $$(pwd)/docs/_build/api/odoc/
diff --git a/README.rst b/README.rst
index 69d0e5522..b09ee0422 100644
--- a/README.rst
+++ b/README.rst
@@ -404,6 +404,10 @@ simple HTTP request:
 The minimal CLI client
 ----------------------
 
-Work in progress.
+Tezos is distributed with two command line tools: a minimal command
+line wallet ``tezos-client``, and an administration tool
+``tezos-admin-client``.
 
-See ``./tezos-client -help`` for available commands.
+Their command line interfaces are described
+:ref:`here<tezos_client_commands>` and
+:ref:`here<tezos_admin_client_commands>`.
diff --git a/docs/api/cli-commands.rst b/docs/api/cli-commands.rst
new file mode 100644
index 000000000..afa6106a0
--- /dev/null
+++ b/docs/api/cli-commands.rst
@@ -0,0 +1,28 @@
+**********************
+Command Line Interface
+**********************
+
+This document is a prettier output of the documentation produced by
+the command line client's ``man`` command. You can obtain similar pages
+using the following shell commands.
+
+::
+
+   tezos-client -protocol ProtoALphaALph man -verbosity 3
+   tezos-admin-client man -verbosity 3
+
+Command line client
+===================
+
+.. _tezos_client_commands:
+
+.. raw:: html
+         :file: tezos-client.html
+
+Administration command line client
+==================================
+
+.. _tezos_admin_client_commands:
+
+.. raw:: html
+         :file: tezos-admin-client.html
diff --git a/docs/index.rst b/docs/index.rst
index ab96e6cee..7bedcac77 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -41,10 +41,11 @@ Welcome to Tezos's documentation!
 
 .. toctree::
    :maxdepth: 2
-   :caption: OCaml API:
+   :caption: APIs:
 
    README
    api/api-inline
+   api/cli-commands
 
 Indices and tables
 ==================
diff --git a/src/lib_stdlib_lwt/cli_entries.ml b/src/lib_stdlib_lwt/cli_entries.ml
index 5ae55de7e..9767a689f 100644
--- a/src/lib_stdlib_lwt/cli_entries.ml
+++ b/src/lib_stdlib_lwt/cli_entries.ml
@@ -929,18 +929,18 @@ let usage ppf ?global_options ?(highlights=[]) commands format verbosity =
           "@[<v>@{<title>Usage@}@,\
            @{<section>\
            @{<command>@{<commandline>\
-           %s @{<opt>[global options]@} command @{<opt>[command options]@}@}@}@,\
+           %s [@{<opt>global options@}] command @{<opt>[command options]@}@}@}@,\
            @{<command>@{<commandline>\
            %s @{<opt>-help@} (for global options)@}@}@,\
            @{<command>@{<commandline>\
-           %s @{<opt>[global options]@} command @{<opt>-help@} (for command options)@}@}\
+           %s [@{<opt>global options@}] command @{<opt>-help@} (for command options)@}@}\
            @}@,@,\
            @{<title>To browse the documentation@}@,\
            @{<section>\
            @{<command>@{<commandline>\
-           %s @{<opt>[global options]@} man (for a list of commands)@}@}@,\
+           %s [@{<opt>global options@}] man (for a list of commands)@}@}@,\
            @{<command>@{<commandline>\
-           %s @{<opt>[global options]@} man @{<opt>-verbosity 3@} (for the full manual)@}@}\
+           %s [@{<opt>global options@}] man @{<opt>-verbosity 3@} (for the full manual)@}@}\
            @}@,@,\
            @{<title>Global options (must come before the command)@}@,\
            @{<commanddoc>%a@}%a\