From 00ab3daa0cf23c0ffca265a9b2dfd958458b4c3e Mon Sep 17 00:00:00 2001
From: Zach Ramsay <zach.ramsay@gmail.com>
Date: Tue, 3 Oct 2017 22:00:48 -0400
Subject: [PATCH] document no empty blocks, closes #605 [ci skip]

---
 docs/index.rst                       | 21 +++++++++---------
 docs/specification/configuration.rst |  8 ++++---
 docs/using-tendermint.rst            | 32 ++++++++++++++++++++++++++++
 3 files changed, 47 insertions(+), 14 deletions(-)

diff --git a/docs/index.rst b/docs/index.rst
index ee1307bf2..0ede0e4e9 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -15,8 +15,6 @@ Welcome to Tendermint!
 Tendermint 101
 --------------
 
-.. maxdepth set to 2 for sexinesss
-.. but use 4 to upgrade overall documentation
 .. toctree::
    :maxdepth: 2
 
@@ -25,9 +23,19 @@ Tendermint 101
    getting-started.rst
    using-tendermint.rst
 
+Tendermint Ecosystem
+--------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   ecosystem.rst
+
 Tendermint Tools
 ----------------
 
+.. the tools/ files are pulled in from the tools repo
+.. see the bottom of conf.py
 .. toctree::
    :maxdepth: 2
 
@@ -38,15 +46,6 @@ Tendermint Tools
    tools/terraform-digitalocean.rst
    tools/benchmarking-and-monitoring.rst
 
-
-Tendermint Ecosystem
---------------------
-
-.. toctree::
-   :maxdepth: 2
-
-   ecosystem.rst
-
 Tendermint 102
 --------------
 
diff --git a/docs/specification/configuration.rst b/docs/specification/configuration.rst
index 81d1c41d0..94801136f 100644
--- a/docs/specification/configuration.rst
+++ b/docs/specification/configuration.rst
@@ -30,14 +30,16 @@ The main config parameters are defined
 
 -  ``consensus.max_block_size_txs``: Maximum number of block txs.
    *Default*: ``10000``
+-  ``consensus.create_empty_blocks``: Create empty blocks w/o txs.
+   *Default*: ``true``
+-  ``consensus.create_empty_blocks_interval``: Block creation interval, even if empty.
 -  ``consensus.timeout_*``: Various consensus timeout parameters
-   **TODO**
 -  ``consensus.wal_file``: Consensus state WAL. *Default*:
-   ``"$TMHOME/data/cswal"``
+   ``"$TMHOME/data/cs.wal/wal"``
 -  ``consensus.wal_light``: Whether to use light-mode for Consensus
    state WAL. *Default*: ``false``
 
--  ``mempool.*``: Various mempool parameters **TODO**
+-  ``mempool.*``: Various mempool parameters
 
 -  ``p2p.addr_book_file``: Peer address book. *Default*:
    ``"$TMHOME/addrbook.json"``. **NOT USED**
diff --git a/docs/using-tendermint.rst b/docs/using-tendermint.rst
index 6e870851f..cc94245cd 100644
--- a/docs/using-tendermint.rst
+++ b/docs/using-tendermint.rst
@@ -126,6 +126,38 @@ Notable options include the socket address of the application
 
 Some fields from the config file can be overwritten with flags.
 
+No Empty Blocks
+---------------
+
+This much requested feature was implemented in version 0.10.3. While the default behaviour of ``tendermint`` is still to create blocks approximately once per second, it is possible to disable empty blocks or set a block creation interval. In the former case, blocks will be created when there are new transactions or when the AppHash changes.
+
+To configure tendermint to not produce empty blocks unless there are txs or the app hash changes, 
+run tendermint with this additional flag:
+
+::
+
+    tendermint node --consensus.create_empty_blocks=false
+
+or set the configuration via the ``config.toml`` file:
+
+::
+
+    [consensus]
+    create_empty_blocks = false
+
+Remember: because the default is to *create empty blocks*, avoiding empty blocks requires the config option to be set to ``false``.
+
+The block interval setting allows for a delay (in seconds) between the creation of each new empty block. It is set via the ``config.toml``:
+
+::
+
+    [consensus]
+    create_empty_blocks_interval = 5
+
+With this setting, empty blocks will be produced every 5s if no block has been produced otherwise,
+regardless of the value of `create_empty_blocks`.
+
+
 Broadcast API
 -------------